SEOshop Documentation

Charging for your app

By default you can charge a monthly fee for your app. This is the price a customer will see in the app store. Additionally you can also offer different subscriptions (like Medium, Large, etc.), or perform single charges.

How it works

  1. You create a new charge (either recurring or onetime)
  2. You redirect the customer to the approvalUrl
  3. The customer approves and is redirected to your callbackUrl
  4. The customer will now be charged

Please note, every charge you create must first be approved by the customer. This charge request will expire after 72 hours.

POST Create a recurring charge

With the following request you can create a new recurring charge. It will return an approvalUrl where you can redirect the customer to. The customer will be charged every month.

Arguments

NameValue
type

Wether this is a recurring or onetime charge

{"type": "recurring|onetime"}
title

The name of the charge as shown to the customer

{"title": "Gold subscription"}
price

The total amount of the charge

{"price":9.95}
callbackUrl

The url we'll send the customer to when they approve or cancel

{"callbackUrl": "https://yourapp.com/return"}
appSubscriptionId

When this is an upgrade pass the subscription you want to upgrade from

{"appSubscriptionId": "{id}"}
DefinitionPOST /app_subscriptions.json
Create a new appSubscription
Example Request
POST /app_subscriptions.json
{
    "appSubscription": {
        "type": "recurring",
        "title": "Gold subscription",
        "price": 9.95,
        "callbackUrl": "https://yourapp.com/return"
    }
}
Example Response
HTTP/1.1 201 Created
{
  "appSubscription": {
    "id": 1,
    "createdAt": "2016-05-24T13:45:07+02:00",
    "updatedAt": "2016-05-24T13:45:51+02:00",
    "type": "recurring",
    "title": "Gold subscription",
    "price": 9.95,
    "status": "active",
    "callbackUrl": "https://yourapp.com/return",
    "approvalUrl": null,
    "cancelUrl": "https://api.webshopapp.com/en/subscriptions/cancel?token={token}"
  }
}

POST Create a onetime charge

With the following request you can create a new onetime charge. It will return an approvalUrl where you can redirect the customer to. The customer will be charged one time on the next invoice.

Arguments

NameValue
type

Wether this is a recurring or onetime charge

{"type": "recurring|onetime"}
title

The name of the charge as shown to the customer

{"title": "Gold subscription"}
price

The total amount of the charge

{"price":9.95}
callbackUrl

The url we'll send the customer to when they approve or cancel

{"callbackUrl": "https://yourapp.com/return"}
DefinitionGET /app_subscriptions.json
Get a list of all appSubscriptions of a shop.
Example Response
HTTP/1.1 200 OK
{
  "appSubscriptions": [
    {
      "id": 1,
      "createdAt": "2016-05-24T13:45:07+02:00",
      "updatedAt": "2016-05-24T13:45:51+02:00",
      "type": "recurring",
      "title": "Gold subscription",
      "price": 9.95,
      "status": "active",
      "callbackUrl": "https://yourapp.com/return",
      "approvalUrl": null,
      "cancelUrl": "https://api.webshopapp.com/en/subscriptions/cancel?token={token}"
    }
  ]
}

When the customer approves or cancels

When the customer approves (or cancels) the charge we send them to the callbackUrl. We pass along the following parameters.

app_subscription_id, cluster_id, language, shop_id, timestamp and the signature.

Always validate the signature to see if the request has not been tempered with. Only the following fields are used to generate the signature: app_subscription_id, language, shop_id, timestamp. Learn more about generating the signature.

With these parameters you can fetch the subscription from the API to see what the current status is and take the appropriate action.

GET Fetch a charge

To get a charge from the API you only need the appSubscriptionId. You'll receive the activate status and other information. Please note that unapproved requests expire in 27 hours.

Arguments

NameValue
id

The unique numeric identifier for the appSubscription.

{"id": "{id}"}
DefinitionGET /app_subscriptions/{appSubscription_id}.json
Get a single appSubscription.
Example Response
HTTP/1.1 200 OK
{
  "appSubscription": {
    "id": 1,
    "createdAt": "2016-05-24T13:45:07+02:00",
    "updatedAt": "2016-05-24T13:45:51+02:00",
    "type": "recurring",
    "title": "Gold subscription",
    "price": 9.95,
    "status": "active",
    "callbackUrl": "https://yourapp.com/return",
    "approvalUrl": null,
    "cancelUrl": "https://api.webshopapp.com/en/subscriptions/cancel?token={token}"
  }
}

POST Upgrade an existing charge

You can upgrade active charges by creating a new charge and passing along the subscription you'd like to upgrade from. Simply pass appSubscriptionId and we'll automatically handle the pro-rated billing. Please note that the customer has to approve the upgrade manually first. Until that time his old subscription remains active.

Arguments

No arguments available.

DefinitionGET /app_subscriptions.json
Get a list of all appSubscriptions of a shop.
Example Response
HTTP/1.1 200 OK
{
  "appSubscriptions": [
    {
      "id": 1,
      "createdAt": "2016-05-24T13:45:07+02:00",
      "updatedAt": "2016-05-24T13:45:51+02:00",
      "type": "recurring",
      "title": "Gold subscription",
      "price": 9.95,
      "status": "active",
      "callbackUrl": "https://yourapp.com/return",
      "approvalUrl": null,
      "cancelUrl": "https://api.webshopapp.com/en/subscriptions/cancel?token={token}"
    }
  ]
}

DELETE Cancel a charge request

If you have created a charge but like to replace it with another charge before the customer has approved? You can do this by sending a DELETE request with the id of the unapproved request.

Arguments

NameValue
id

The unique numeric identifier for the appSubscription.

{"id": "{id}"}
DefinitionDELETE /app_subscriptions/{appSubscription_id}.json
Delete a appSubscription
Example Response
HTTP/1.1 204 No Content
Was this article helpful? Yes No
One moment please
Thanks for your feedback.