Description of service

The subscription service is used by merchants to administrate subscriptions for a customer. The merchant will receive callbacks from Sweetpay when for example the subscription is executed or paid. See this link for all callback events.

The service is built on the concept of subscriptions, which contain both the product data and customer data.

API URL

Server Value
Stage https://api.stage.sweetpay.com/subscription
Production https://api.sweetpay.com/subscription

Requests

Create a subscription

Key Value
URL /v1/create
Method POST
Body CreateSubscriptionRequest
Response APIResponse with Subscription as payload

CreateSubscriptionRequest

Property Type Mandatory Description
country Country Yes The code for the country the customer is living in.
interval SubscriptionInterval Yes How often the subscription will be executed.
currency Currency Yes The currency of the amount. For example “SEK”.
amount Decimal Yes The amount to bill the customer each interval.
merchantId String Yes The merchant id for the owner of this subscription, as supplied by Sweetpay.
startsAt Date No The start date of the subscription. Defaults to today's date.
maxExecutions Integer No The amount of invoices to send out before the subscription expires.
language Language No The language this person will use on his account pages. If omitted, the merchant’s default language will be used.
merchantCustomerId String No Merchant-unique identifier for the customer the subscription is for. If omitted, the ID will be looked up from the customer details. If there is no matching customer, one will be created and the merchantCustomerId will be generated by Paylevo. Alphanumeric characters, dash and underscore are allowed.
ssn String No Lookup attribute. The social security number (or personal number or similar) used to look up a person.
org String No Lookup attribute. The organization number (or VAT number of similar) used to look up an organization.
phone String No Lookup attribute. The phone number used to look up a customer.
email String No Lookup attribute. The email address used to lookup a customer.
billingPhone String No The phone number to use for billing. Will be used instead of phone to bill the customer if set.
billingEmail String No The email address to use for billing. Will be used instead of email to bill the customer if set.
billingName Name No The name to use on the invoice, if omitted the looked up name will be used.
billingAddress Address No The address to send any physical invoices to. If this is omitted, the looked up information will be used.
billingAttest String No Just for B2B. The person in the organization to receive the subscription's invoices. This name will only be displayed on the invoice.
comment String No A string comment to be displayed on the invoice. There are three template words which will be substituted by data in Paylevo’s system. These are: {merchant}, {starts} and {ends}. See below for an example and an explanation. For example” Payment to {merchant} for the period {starts} - {ends}” will be displayed as “Payment to YourName for the period 2015-01-01 - 2015-01-31”, assuming that the company name is “YourName”, that the interval of the subscription is “MONTHLY” and that the next execution date is “2015-02-01” and that the execution date for this invoice was “2015-01-01”. Note that comment can be set to a default value in Sweetpay’s system.
vat Decimal No The VAT percentage of the amount. If omitted, the default VAT rate for your account will be used. Provided that VAT is configured to be displayed on the invoice.
attachment String No Your own meta data about the subscription. If you want to provide a JSON object, please base64 encode it first.
callbackUrl String No The URL to send callbacks to. If this is empty, the default callback URL set in Sweetpay's database will be used.

Update a subscription

Key Value
URL /v1/{subscriptionId}/update
Method POST
Body UpdateSubscriptionRequest
Response APIResponse with Subscription as payload

UpdateSubscriptionRequest

NOTE: No attribute can be set to null. As such, explicit null values will be treated as a missing parameter.

Property Type Mandatory Description
startsAt Date No The date when the subscription should be started. If omitted, it will be set to today. If the date is in the past, it will be retroactively executed until it catches up. This means that if Subscription.interval is set to “MONTHLY” and you set this value to one month back in time, the customer will receive an invoice requiring them to pay for two months. Paylevo will decide at what time during the day to execute.
maxExecutions Integer No The max executions of the subscription. This is recommended.

Regret a subscription

Key Value
URL /v1/{subscriptionId}/regret
Method POST
Body Empty
Response APIResponse with Subscription as payload

Query a subscription

Key Value
URL /v1/{subscriptionId}/query
Method GET
Body Empty
Response APIResponse with Subscriptions as payload

Search for subscriptions

Key Value
URL /v1/search
Method POST
Body SearchRequest
Response APIResponse with a list of Subscriptions as payload

SearchRequest

At least one of the below need to be set.

Property Type Description
country Country The code for the country the customer is living in.
merchantId String The merchant who did the subscription. The full id will be searched with equals.
merchantCustomerId String Merchant-unique identifier for the customer the subscription is for. The full ID will be searched with equals.
merchantItemId String The merchant-unique item to search for. Will use equals, not contains.

ssn | String | The social security number for a person. Accepts a substring and will search with contains. org | String | The organization number for an organization. Accepts a substring and will search with contains. phone | String | The phone number for the customer. Accepts a substring and will search with contains. Spaces and dashes will be stripped before searching. email | String | The email address for the customer. Accepts a substring and will search with contains. name | String | The name of the customer. Accepts a substring and will search with contains. Will strip spaces before searching. address | String | The address of the customer.

List a subscription's log

Key Value
URL /v1/{subscriptionId}/log
Method GET
Body Empty
Response APIResponse with a list of SubscriptionHistory as payload

Envelopes

CallbackEnvelope

Note that there are several versions of the callback structure. If need be, you can use the latest version which can be found here. In that case, tell Sweetpay that you want to use the latest version of the callback structure.

CallbackEnvelope

Property Type Mandatory Description
createdAt Datetime Yes The time the event took place in Paylevo's system.
sentAt Datetime Yes The time the callback was sent, this will be updated for resends.
callbackId Integer Yes A unique ID to be used for idempotence. It is highly advised that you save this ID in the database to make sure that you have not handled the callback before.
event SubscriptionEvent Yes The event that triggered the callback.
payload Subscription Yes Will represent the state of the subscription object when the event occurred. It may not always be a good idea to update your local database with the contents of a callback as it may be out-dated. Therefore, make sure to check the createdAt before updating your local database.

ApiResponse

Property Type Mandatory Description
status ApiStatus Yes The status of the request.
createdAt Datetime Yes When the response was created.
payload Subscription or list of Subscriptions No A subscription object or a list of them, will only be present if the status is OK.

Objects

Subscription

Property Type Mandatory Description
subscriptionId Integer Yes The unique ID for the subscription, to be used in further interactions.
merchantId String Yes The merchant who owns the subscription.
state SubscriptionState Yes The state of the subscription.
createdAt Datetime Yes The timestamp (ISO format) when the subscription was created.
startsAt Date string Yes The date (YYYY-MM-DD) when the subscription should be started. If the date is in the past, it will be retroactively executed until it catches up. This means that if the subscriptions interval is set to “MONTHLY” and you set this value to one month back in time, the customer will receive an invoice requiring them to pay for two months. Paylevo will decide at what time during the day to execute.
customer Customer Yes A SubscriptionCustomer object describing the customer.
billing Billing Yes The billing information of the customer.
interval SubscriptionInterval Yes How often subscriptions will be executed.
currency Currency Yes The currency of the amount.
amount Decimal Yes The price for this subscription.
maxExecutions Integer No The number of invoices to send out before expiring the order.
endsAt Date string No DEPRECATED: Use maxExecutions instead. The date when the subscription should be ended. If this is at the same day as an execution, that day will be executed.
lastExecutionAt Date No The date the last execution was run, or null if no execution has been made.
nextExecutionAt Date No The date the next execution should be run, or null if not running.
merchantItemId String No The merchant-unique id for the item, alphanumeric. Can be used to for example track your products in Paylevos system.
merchantCustomerId String No The merchant-unique ID for the customer.
vat Decimal No The VAT percentage used for the subscription.
attachment String No The attachment with meta data you have specified, or null if no meta data was provided.
executions Integer No The number of times the subscription has been executed.

Customer

Property Type Mandatory Description
country Country Yes The country the customer lives in.
customerId Integer Yes Sweetpay's internal customer ID.
status String Yes Will be OK if the customer was creditworthy, otherwise another value will be set.
phone String No The phone for the customer.
ssn String No The SSN for the customer.
org String No The organisation number for the customer.
email String No The email for the customer.
name Name No The name for the customer.
address Address No The invoice address for the customer.

Billing

Property Type Mandatory Description
country Country No The country the customer lives in.
phone String No The phone for the customer, may be absent.
ssn String No The SSN for the customer, may be absent.
org String No The organisation number for the customer, may be absent.
email String No The email for the customer, may be absent.
name Name No The name for the customer, be not be absent if the subscription was successful. “first last” format is used for persons.
address Address No The invoice address for the customer, may not be absent if the subscription was successful.

SubscriptionHistory

Property Type Mandatory Description
event SubscriptionEvent Yes The type of the event which generated this entry.
sessionId String No A Paylevo-unique identifier for the session that created the history entry. This may be null for the events that are not concerning a session, for example _CREATED and _UPDATED. A session is when Paylevo interacts with a customer. Note also that some events will have the same sessionId because they all belong to the same session. An example of this is _EXECUTED, _SENT, _PAID and _UNNECESSARY, which relates to the same invoice.
createdAt Datetime Yes When the event took place.
invoiceNumber String No The invoice number. Will be absent for the requests not concerning invoices.
reservationId Integer No The ID of the underlying reservation.

Constants

SubscriptionInterval

Value Description
MONTHLY Execute monthly.
QUARTERLY Execute quarterly.
HALF_YEARLY Execute once every half year.
YEARLY Execute yearly.

SubscriptionState

The states a subscription can have.

Value Description
CREATED The subscription has been created but not executed yet. The subscription in other words active.
RUNNING The subscription is active and running. When a subscription is running it must mean that it hasn't been regretted or expired. This is the state the subscription obtains when it has been executed for the first time. It can in other words be seen as an active subscription.
WAITING_TO_BE_EXPIRED The subscription is waiting to be expired. This indicates that no further invoices will be sent out for the subscription. However, when the subscription is in this state, the subscription can still be prolonged.
EXPIRED The subscription is no longer active. A subscription becomes expired when its endsAt date has passed (or is today). When a subscription is EXPIRED, it can be seen as inactive.
REGRETTED The subscription has been regretted. When a subscription is REGRETTED, it can be seen as inactive.

SubscriptionEvent

Events that may occur at Sweetpay. Every event triggers a callback.

Value Description
SUBSCRIPTION_CREATED The subscription was created.
SUBSCRIPTION_UPDATED The subscription was updated. This means that Subscription.endsAt or Subscription.startsAt was updated.
SUBSCRIPTION_STARTED The subscription was executed for the first time. When this event is triggered the state of the subscription has changed to “RUNNING”. See SUBSCRIPTION_EXECUTED for more information about execution.
SUBSCRIPTION_WAITING_TO_BE_EXPIRED The subscription is now waiting to be expired, meaning that no further invoices will be sent out. This event indicates that the subscription changed state to WAITING_TO_BE_EXPIRED.
SUBSCRIPTION_EXPIRED The subscription expired. This means that Subscription.endsAt has been passed and that the subscription is no longer active.
SUBSCRIPTION_REGRETTED The subscription was regretted.
SUBSCRIPTION_QUEUED The subscription was queued for execution.
SUBSCRIPTION_EXECUTION The subscription's execution succeeded.
SUBSCRIPTION_FAILED_ILLEGIBLE The subscription execution failed because the customer was illegible.
SUBSCRIPTION_FAILED_PENDING_INVOICES The subscription execution failed because there were too many pending invoices.
SUBSCRIPTION_FAILED_NOT_ENOUGH_CREDIT The subscription execution failed because the customer doesn’t have enough credits.
SUBSCRIPTION_FAILED_IN_COLLECTION The subscriptions execution failed because the customer is in debt collection.
SUBSCRIPTION_FAILED_OVERDUE The subscription failed because the customer is overdue.
SUBSCRIPTION_FAILED_TEMPORARILY The subscription could not be executed but it might work later. This means that Paylevo will try to execute it again.
SUBSCRIPTION_INVOICE_CREATED An invoice for the subscription was created.
SUBSCRIPTION_INVOICE_SENT The subscription's customer was invoiced.
SUBSCRIPTION_INVOICE_SENT The subscription's customer was invoiced.
SUBSCRIPTION_INVOICE_PAID The subscription was paid.
SUBSCRIPTION_INVOICE_REMINDED The subscription's customer was reminded to pay its pending invoice.
SUBSCRIPTION_INVOICE_REMINDED_FINAL The final reminder of the invoice was sent out. Only applicable in some countries.
SUBSCRIPTION_INVOICE_IN_COLLECTION The subscription’s invoice was sent to debt collection.
SUBSCRIPTION_INVOICE_UNNECESSARY The invoice was set to unnecessary.