ApplicationCharge

Request to charge a shop a one-time fee by issuing this call with the name the charge should appear under (on the shop owner’s invoice), the price your application is charging, and a return_url to where Shopify will redirect the shop owner to after they have accepted or declined the charge.

Setting the test flag to true will set the ApplicationCharge to not actually charge the credit card it otherwise would.

After this request returns, an ApplicationCharge has been created, but is held in a pending state until the shop owner has accepted or declined it.

Proceed by redirecting the shop owner to the confirmation_url set in the response where they may accept or decline the charge.

After the charge has been accepted or declined, Shopify redirects the shop owner to the return_url set in the request. At this point the shop is either in an accepted or declined state. In order to actually receive payment for this charge it must be activated by your application.

Reminder

Test or demo shops may not be charged.

What can you do with ApplicationCharge?

The Shopify API lets you do the following with the ApplicationCharge resource. More detailed versions of these general actions may be available:

ApplicationCharge Properties

confirmation_url
{ "confirmation_url" : "https://apple.myshopify.com/admin/charges/confirm_application_charge?id=1012637313&signature=BAhpBIGeWzw%3D--17779c1efb4688e9cfa653a3245f923b4f1eb140" }

The URL that the customer is taken to, to accept or decline the one-time application charge.

created_at
{ "created_at" : "2013-06-27T08:48:27-04:00" }

The date and time when the one-time application charge was created. The API returns this value in ISO 8601 format.

id
{ "id" : 675931192 }

A unique numeric identifier for the one-time application charge.

name
{ "name" : "Super Duper Expensive action" }

The name of the one-time application charge.

price
{ "price" : "100.00" }

The price of the one-time application charge.

return_url
{ "return_url" : "http://super-duper.shopifyapps.com" }

The URL the customer is sent to once they accept/decline a charge.

status
{ "status" : "accepted" }

The status of the application charge. Valid values are:

  • pending: The application charge is pending.
  • accepted: The application charge has been accepted.
  • declined: The application charge has been declined.
  • expired: The application charge was not accepted within 2 days of being created.

test
{ "test" : null }

States whether or not the application charge is a test transaction. Valid values are "true" or "null".

updated_at
{ "updated_at" : "2013-06-27T08:48:27-04:00" }

The date and time when the charge was last updated. The API returns this value in ISO 8601 format.

Endpoints

POST/admin/application_charges.json

Create a new one-time application charge.

Create a one-time test charge that will not cause a credit card to be charged

POST /admin/application_charges.json
{
  "application_charge": {
    "name": "Super Duper Expensive action",
    "price": 100.0,
    "return_url": "http:\/\/super-duper.shopifyapps.com",
    "test": true
  }
}
View Response
HTTP/1.1 201 Created
{
  "application_charge": {
    "id": 1012637314,
    "name": "Super Duper Expensive action",
    "api_client_id": 755357713,
    "price": "100.00",
    "status": "pending",
    "return_url": "http:\/\/super-duper.shopifyapps.com\/",
    "created_at": "2016-06-20T13:33:14-04:00",
    "updated_at": "2016-06-20T13:33:14-04:00",
    "test": true,
    "charge_type": null,
    "decorated_return_url": "http:\/\/super-duper.shopifyapps.com\/?charge_id=1012637314",
    "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/1012637314\/confirm_application_charge?signature=BAhpBIKeWzw%3D--c7b967009011241b34df9c897548fc07bdf0ebd6"
  }
}

Trying to create a charge without a price or name will return an error

POST /admin/application_charges.json
{
  "application_charge": {
    "name": ""
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "price": [
      "must be greater than zero"
    ],
    "name": [
      "can't be blank"
    ]
  }
}

Create a one-time charge called 'Super Duper Expensive action' for $100.00 USD

POST /admin/application_charges.json
{
  "application_charge": {
    "name": "Super Duper Expensive action",
    "price": 100.0,
    "return_url": "http:\/\/super-duper.shopifyapps.com"
  }
}
View Response
HTTP/1.1 201 Created
{
  "application_charge": {
    "id": 1012637316,
    "name": "Super Duper Expensive action",
    "api_client_id": 755357713,
    "price": "100.00",
    "status": "pending",
    "return_url": "http:\/\/super-duper.shopifyapps.com\/",
    "created_at": "2016-06-20T13:33:16-04:00",
    "updated_at": "2016-06-20T13:33:16-04:00",
    "test": null,
    "charge_type": null,
    "decorated_return_url": "http:\/\/super-duper.shopifyapps.com\/?charge_id=1012637316",
    "confirmation_url": "https:\/\/apple.myshopify.com\/admin\/charges\/1012637316\/confirm_application_charge?signature=BAhpBISeWzw%3D--5768ca0ce874fb7ad082c923295f9aba1d0e11d5"
  }
}
GET/admin/application_charges/675931192.json
fields

comma-separated list of fields to include in the response

Retrieve one-time application charge

GET /admin/application_charges/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "application_charge": {
    "id": 675931192,
    "name": "iPod Cleaning",
    "api_client_id": 755357713,
    "price": "5.00",
    "status": "accepted",
    "return_url": "http:\/\/google.com",
    "created_at": "2016-06-20T13:33:03-04:00",
    "updated_at": "2016-06-20T13:33:03-04:00",
    "test": null,
    "charge_type": null,
    "decorated_return_url": "http:\/\/google.com?charge_id=675931192"
  }
}
GET/admin/application_charges.json

All charges that have been requested are retrieved by this request.

since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Retrieving all one-time charges since a specified ID

GET /admin/application_charges.json?since_id=556467234
View Response
HTTP/1.1 200 OK
{
  "application_charges": [
    {
      "id": 675931192,
      "name": "iPod Cleaning",
      "api_client_id": 755357713,
      "price": "5.00",
      "status": "accepted",
      "return_url": "http:\/\/google.com",
      "created_at": "2016-06-20T13:33:03-04:00",
      "updated_at": "2016-06-20T13:33:03-04:00",
      "test": null,
      "charge_type": null,
      "decorated_return_url": "http:\/\/google.com?charge_id=675931192"
    }
  ]
}

Retrieving all one-time charges

GET /admin/application_charges.json
View Response
HTTP/1.1 200 OK
{
  "application_charges": [
    {
      "id": 556467234,
      "name": "Green theme",
      "api_client_id": 755357713,
      "price": "120.00",
      "status": "accepted",
      "return_url": "http:\/\/google.com",
      "created_at": "2016-06-20T13:33:03-04:00",
      "updated_at": "2016-06-20T13:33:03-04:00",
      "test": null,
      "charge_type": "theme",
      "decorated_return_url": "http:\/\/google.com?charge_id=556467234"
    },
    {
      "id": 675931192,
      "name": "iPod Cleaning",
      "api_client_id": 755357713,
      "price": "5.00",
      "status": "accepted",
      "return_url": "http:\/\/google.com",
      "created_at": "2016-06-20T13:33:03-04:00",
      "updated_at": "2016-06-20T13:33:03-04:00",
      "test": null,
      "charge_type": null,
      "decorated_return_url": "http:\/\/google.com?charge_id=675931192"
    }
  ]
}
POST/admin/application_charges/675931192/activate.json

Activate a previously accepted one-time application charge.

Activate a one-time charge

POST /admin/application_charges/#{id}/activate.json
{
  "application_charge": {
    "id": 675931192,
    "name": "iPod Cleaning",
    "api_client_id": 755357713,
    "price": "5.00",
    "status": "accepted",
    "return_url": "http:\/\/google.com",
    "created_at": "2016-06-20T13:33:03-04:00",
    "updated_at": "2016-06-20T13:33:03-04:00",
    "test": null,
    "charge_type": null,
    "decorated_return_url": "http:\/\/google.com?charge_id=675931192"
  }
}
View Response
HTTP/1.1 200 OK
{
  "application_charge": {
    "id": 675931192,
    "name": "iPod Cleaning",
    "api_client_id": 755357713,
    "price": "5.00",
    "status": "active",
    "return_url": "http:\/\/google.com\/",
    "created_at": "2016-06-20T13:33:03-04:00",
    "updated_at": "2016-06-20T13:33:15-04:00",
    "test": null,
    "charge_type": null,
    "decorated_return_url": "http:\/\/google.com\/?charge_id=675931192"
  }
}