Subscription API - Create subscription

Create subscription

POST *base*/subscription/order Authentication : API Key

Add a subscription with payment details, will not be completed/registered as a completed subscription until subscription/payment has been called.

Parameters

name sname
string
required

First and last name of the customer

email
string
required

Customer e-mail

address coaddress city state zipcode phoneNumber
string
optional

Address information for the customer

language
string
optional

The language code for created customer.

country
string
required

The country of the customer. ISO-Alpha-2 (SE, US, GB etc)

package
array
required

Array with Package IDs for each package you want in the subscription.

For example: package[]=3232&package[]=4344

payment
string
required

URI of payment plugin to be used. Needs to be set up before as a payment plugin for the store.

There are only a few payment plugins that support subscription services. Please make sure the payment plugin you set up allows it.

payment_url
string
optional

A url where the customer should be redirected to when payment is completed.

pnr
string
optional

The social security number for the user, used for some payment plugins to invoice the customer.

sendNewsletter
boolean
optional

If the user opted in to a newsletter subscription.

startdate
datetime
optional

Default today. The date when the subscription should start. The first order will be created first after this date.

interval
int
optional

Default 14. The interval between each subscription. Depending on intervaltype it will be months or days.

intervaltype
enum
optional

Default D. The type of interval for the subscription.

  • M interval is in months.
  • D interval is in days.
consent
object
optional

A list of consents the customer agreed to. The key of each item in the object is the key for the consent. If the consent key does not exists already, it will be added automatically.

For example like this: consent[newsletter_consent][consent_name]=boop

consent_name
string
optional

The name of the consent.

consent_text
string
optional

The description of the consent.

consent_version
string
optional

The version of the consent.

consent_language
string
optional

The language of the consent. No validation is made on this field for the formatting of the language code.

Request example

POST <base>/subscription/order HTTP/1.1
Content-Type: application/x-www-form-urlencoded

name=Kalle&sname=Anka&address=Paradisäppelvägen+9&
coaddress=&city=Ankeborg&state=&zipcode=12345&
country=SE&email=kalle.anka@example.com&package[]=1&package[]=3&
payment=nets[&pnr=880101-7845]&
language=SV

Example Request with consents:

POST <base>/subscription/order? HTTP/1.1
Content-Type: application/x-www-form-urlencoded

name=Kalle&sname=Anka&address=Paradisäppelvägen+9&coaddress=&
city=Ankeborg&state=&zipcode=12345&country=SE&
email=kalle.anka@example.com&package[]=1&package[]=3&
payment=nets[&payment_url=https://...][&pnr=880101-7845]&
language=SV&
consent[direct_marketing]=1&
consent_name[direct_marketing]=Direct%20Marketing&
consent_version[direct_marketing]=1.1&
consent[newsletter]=1&consent_name[newsletter]=Newsletter&
consent_version[newsletter]=v2&consent_language[newsletter]=sv_SE

Response

200 Content-type: application/json

status
string
required

ok if success, else a message explaining what went wrong.

id
int
required

The ID of the subscription that was created.

payment
object
optional

A payment object with information on how finalize the payment.

url
string
optional

A URL to redirect the user to. This could be to an external payment provider depending on the payment plugin.

value
string
optional

The total value of the subscription.

currency
string
optional

The currency that the subscription was registered with, SEK, USD, EUR, etc.

msg
string
optional

If status returns no, this value should send back a message why it failed.

Response examples

HTTP/1.1 200 OK
Content-type: application/json

{
  "status": "ok",
  "id": 3,
  "payment": {
    "url": "https://...",
    "value": "123.50",
    "currency": "SEK"
  }
}

Error example

{
  "status": "Could not register customer",
  "error": true,
  "errors": [
    "email",
    "payment"
  ]
}

Bad payment method:

{
    "status": "Bad Payment Method",
    "error": true,
    "message": "Error message"
}

Previous article: Subscription API