Seal Subscriptions Merchant API Documentation


What is the Seal Subscriptions Merchant API?

The Seal Subscriptions Merchant API is a public REST API for Seal Subscriptions app, which allows merchants to retrieve details about their subscriptions, subscription rules and create webhooks to get notified whenever a specific object changes in the app.
The full documenation of what you can do with the API is listed on this page.

Feel free to use our API client, which was created to save you some valuable time. You can fork it from our Github page: https://github.com/SealSubscriptions/Seal-Subscriptions-php-API-client

Authentication

The API client authenticates itself with the API token which can be found for each shop in the Seal Subscriptions app > Settings > General Settings > API. The token has to be sent as a value for the X-Seal-Token header. Token is unique for each shop and should be protected the same way you protect your usernames and passwords.

Retrieve subscriptions

The subscription retrieval can be done with a simple GET call to a /subscriptions endpoint.
Here is an example of such call:
curl -X GET \
  https://app.sealsubscriptions.com/shopify/merchant/api/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

You can also search for subscriptions by customer's email, first name or last name with the query GET parameter.
Here is an example on how to find subscriptions that contain a name John:
curl -X GET \
  https://app.sealsubscriptions.com/shopify/merchant/api/subscriptions?query=john \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

Subscriptions are always paginated (50 subscriptions per page) and you can define which page you want with the page GET parameter.
curl -X GET \
  https://app.sealsubscriptions.com/shopify/merchant/api/subscriptions?page=2 \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

Here is a list of available get parameters with description of available values you can use:
  • query: value can be any search string. Default value is an empty string.
  • page: value can be any number and represents the requested page. Default value is 1.
  • paused-only: value can be "true" or "false". Default value is "false."
  • cancelled-only: value can be "true" or "false". Default value is "false."


Get more info about a specific subscription

You can retrieve a specific subscription and all info related to it with a GET call to a /subscription endpoint.
Here is an example of such call:
curl -X GET \
  https://app.sealsubscriptions.com/shopify/merchant/api/subscription?id=12345 \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'


Retrieve subscription rules

You can also get list of subscription ruls with a GET call to a /subscription-rules endpoint.
Here is an example of such call:
curl -X GET \
  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-rules?page=1 \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'


Retrieve specific subscription rule

You can retrieve a specific subscription rule with a GET call to a /subscription-rule endpoint, where you add the ID of the rule as a GET parameter.
Here is an example of such call:
curl -X GET \
  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-rule?id=12345 \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'


Create a webhook

To create a webhook which will be executed whenever a subscription is created, send a POST request to /webhooks endpoint.
curl -X POST \
  https://app.sealsubscriptions.com/shopify/merchant/api/webhooks \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
  -d '{
	"topic": "subscription/created", 
	"address": "YOUR_HTTPS_WEBHOOK_ADDRESS"
  }'

When the specified action happens (e.g. subscription is created), our system will send a request with the subscription details to the webhook address you specified in your webhook configuration. Our system will try to deliver the webhook for up to 20 times until your server responds with a HTTP code of 200 OK within 5 seconds. If the webhook can't be delivered after 20 tries, then the whole webhook configuration will be removed.

The payload of each webhook request (and other API responses) will be signed with a HMAC code which will be sent as the value of the X-Seal-Hmac-Sha256 header. The HMAC code will be computed with the JSON encoded webhook payload and the Seal API secret. You can get the Seal API secret of the shop you are making requests for in Seal Subscriptions app > Settings > General Settings > API. It is highly recommended to verify the HMAC signature and reject the content if the signatures don't match. HMAC signature allows you to verify the integrity and authenticity of the message.
You can see how you can verify the signature in our PHP Library available on Github.
https://github.com/SealSubscriptions/Seal-Subscriptions-php-API-client

The currently available webhook topics are:
  • subscription/created
  • subscription/updated
  • subscription_rule/created
  • subscription_rule/updated

This is how you can get your current webhooks:
curl -X GET \
  https://app.sealsubscriptions.com/shopify/merchant/api/webhooks \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

And this is how you delete a specific webhook:
curl -X DELETE \
  https://app.sealsubscriptions.com/shopify/merchant/api/webhooks?id=12345 \
  -H 'Content-Type: application/json' \
  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

This is a sample payload of the subscription_rule/created webhook:
{
    "id": 123124,
    "name": "Monthly subscription",
    "option": "Deliver every",
    "payment_type": "auto-charge",
    "product_variants": [{
            "product_id": "431512499999999",
            "variant_id": null
        }, {
            "product_id": "43151299999999",
            "variant_id": null
        }
    ],
    "selling_plans": [{
            "name": "Monthly subscription",
            "option": "month",
            "delivery_interval": "month",
            "delivery_interval_count": 1,
            "billing_interval": "month",
            "billing_interval_count": 1,
            "pricing_policy_fixed_adjustment_type": "",
            "pricing_policy_fixed_adjustment_value": "",
            "pricing_policy_recurring_adjustment_type": "",
            "pricing_policy_recurring_adjustment_value": "",
            "pricing_policy_recurring_after_cycle": 1,
            "pricing_policy_recurring_active": 0,
            "selling_plan_id": "123123123",
            "billing_min_cycles": 0, /* 0 represents an unset value*/
            "billing_max_cycles": 0, /* 0 represents an unset value*/
            "description": "Subscribe"
        }
    ]
}

This is a sample payload of the subscription/updated webhook:
{
    "id": 123123,
    "order_placed": "2021-05-25T05:17:59-04:00",
    "internal_id": 1038,
    "delivery_interval": "2 week",
    "billing_interval": "2 week",
    "order_id": "12312312313",
    "email": "test@sealsubscriptions.com",
    "currency": "USD",
    "first_name": "John",
    "last_name": "Doe",
    "s_first_name": "John",
    "s_last_name": "Doe",
    "s_address1": "Seal Subscriptions street 5",
    "s_address2": "",
    "s_phone": "132313",
    "s_city": "New York",
    "s_zip": "10001",
    "s_province": "New York",
    "s_country": "United States",
    "s_company": "",
    "s_country_code": "US",
    "s_province_code": "NY",
    "b_first_name": "",
    "b_last_name": "",
    "b_address1": "",
    "b_address2": "",
    "b_phone": "",
    "b_city": "",
    "b_zip": "",
    "b_province": "",
    "b_country": "",
    "b_company": "",
    "b_country_code": "",
    "b_province_code": "",
    "total_value": 1776,
    "admin_note": "",
    "subscription_type": 2,
    "status": "ACTIVE",
    "customer_id": "15512324",
    "billing_min_cycles": 3,
    "billing_max_cycles": 15,
    "note": "",
    "note_attributes": [],
    "edit_url": "", /* Redacted in documentation, as this URL has to be kept safe */
    "items": [{
            "id": 1234,
            "product_id": "",
            "variant_id": "",
            "title": "Two teddy bears",
            "variant_sku": "2BEARS-MEDIUM",
            "quantity": 1,
            "price": "1776.0",
            "total_discount": "0",
            "discount_per_item": "",
            "taxable": 1,
            "requires_shipping": 1,
            "original_price": "1776.0",
            "original_amount": 1776,
            "discount_value": 0,
            "discount_amount": 0,
            "final_price": "1776.0",
            "final_amount": 1776,
            "properties": [],
            "cycle_discounts": []
        }
    ],
	/* Billing attempts were modified before adding them to the API documentation, so the dates in this sample are not correct according to the desired delivery schedule */
    "billing_attempts": [{
            "id": 2343421,
            "date": "2021-10-12T09:00:00+00:00",
            "status": "completed",
            "order_id": "564564121223",
            "error_code": "",
            "error_message": "",
            "triggered_manually": ""
        }, {
            "id": 234234,
            "date": "2021-11-26T09:00:00+00:00",
            "status": "",
            "order_id": "",
            "error_code": "",
            "error_message": "",
            "triggered_manually": ""
        }
    ],
    "invoices": [],
    "fulfillment_orders": [],
    "tags": [],
    "log": []
}