Skip to main content
POST
/
v1
/
subscriptions
Create a subscription
curl --request POST \
  --url https://api.yorlet.com/v1/subscriptions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "collection_method": "charge_automatically",
  "customer": "<string>",
  "interval": "month",
  "add_invoice_items": [
    {
      "amount": 123,
      "currency": "<string>",
      "description": "<string>",
      "tax_percent": 50,
      "transfer_behavior": "automatic",
      "type": "charge",
      "metadata": {},
      "price": "<string>",
      "tax_rate": "<string>",
      "transfer_destination": "<string>",
      "unit": "<string>"
    }
  ],
  "billing_anchor": 123,
  "billing_anchor_config": {
    "day_of_month": 16
  },
  "coupon": "<string>",
  "custom_fields": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "days_before_collection": 3,
  "days_until_due": 1,
  "default_payment_method": "<string>",
  "description": "<string>",
  "end_date": 123,
  "end_date_config": {
    "day": 16,
    "month": 6,
    "year": 123
  },
  "metadata": {},
  "phases": [
    {
      "start_date": 123,
      "items": [
        {
          "price_data": {
            "amount": 123,
            "currency": "<string>",
            "tax_percent": 123
          },
          "type": "charge",
          "description": "<string>",
          "metadata": {},
          "price": "<string>",
          "proration_behavior": "create_prorations",
          "schedule": [
            {
              "amount": 123,
              "effective_at": 123
            }
          ],
          "tax_rate": "<string>",
          "transfer_behavior": "automatic",
          "transfer_destination": "<string>",
          "unit": "<string>"
        }
      ]
    }
  ],
  "start_date": 123,
  "start_date_config": {
    "day": 16,
    "month": 6,
    "year": 123
  },
  "application": "<string>",
  "currency": "gbp",
  "first_invoice_creation": "immediately",
  "interval_count": 123,
  "invoice_settings": {
    "custom_fields": [
      {
        "name": "<string>",
        "value": "<string>"
      }
    ]
  },
  "items": [
    {
      "price_data": {
        "amount": 123,
        "currency": "<string>",
        "tax_percent": 123
      },
      "type": "charge",
      "description": "<string>",
      "metadata": {},
      "price": "<string>",
      "proration_behavior": "create_prorations",
      "schedule": [
        {
          "amount": 123,
          "effective_at": 123
        }
      ],
      "tax_rate": "<string>",
      "transfer_behavior": "automatic",
      "transfer_destination": "<string>",
      "unit": "<string>"
    }
  ],
  "use_future_billing_date": true
}
'
{
  "id": "<string>",
  "created": 123,
  "object": "subscription",
  "application": "<string>",
  "billing_anchor": 123,
  "billing_anchor_config": {
    "day_of_month": 16
  },
  "cancel_at": 123,
  "canceled_at": 123,
  "collection_method": "charge_automatically",
  "coupon": "<string>",
  "currency": "gbp",
  "current_period_end": 123,
  "current_period_start": 123,
  "custom_fields": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "customer": "<string>",
  "days_before_collection": 3,
  "days_until_due": 1,
  "default_payment_method": "<string>",
  "description": "<string>",
  "end": 123,
  "interval": "month",
  "interval_count": 123,
  "next_period_end": 123,
  "next_period_start": 123,
  "pause_collection": {
    "behavior": "draft",
    "resumes_at": 123
  },
  "payment_settings": {
    "payment_method_types": [
      "autogiro"
    ]
  },
  "phases": [
    {
      "start_date": 123,
      "items": [
        "<unknown>"
      ]
    }
  ],
  "start": 123,
  "status": "active",
  "account": "<string>",
  "deleted": false,
  "metadata": {}
}

Authorizations

​
Authorization
string
header
required

API Key authentication. Use "Bearer YOUR_API_KEY".

Body

application/json
​
collection_method
enum<string>
required

The collection method for the subscription.

Available options:
charge_automatically,
send_invoice
​
customer
string
required

The identifier of the customer to create the subscription for.

​
interval
enum<string>
required

The billing interval for the subscription.

Available options:
month,
week,
custom
​
add_invoice_items
object[] | null

A list of invoice items to add to invoices created by the subscription.

Maximum array length: 10
​
billing_anchor
integer | null

The reference point that aligns future billing cycle dates.

​
billing_anchor_config
object

Configuration for the billing anchor.

​
coupon
string | null

The identifier of the coupon to apply to the subscription.

​
custom_fields
object[]

Custom fields attached to the subscription invoices.

Maximum array length: 4
​
days_before_collection
integer

The number of days before the due date to attempt collection.

Required range: 0 <= x <= 7
​
days_until_due
integer | null

The number of days until the invoice is due.

Required range: x >= 0
​
default_payment_method
string | null

The identifier of the default payment method for the subscription.

​
description
string

The description of the subscription.

​
end_date
integer | null

The end date of the subscription.

​
end_date_config
object

Configuration to compute the end date of the subscription.

​
metadata
object

Set of key-value pairs to attach to the subscription.

​
payment_settings
object

The payment settings for the subscription.

​
phases
object[] | null

The phases of the subscription. Required when interval is custom.

Minimum array length: 1
​
start_date
integer | null

The start date of the subscription.

​
start_date_config
object

Configuration to compute the start date of the subscription.

​
application
string | null

The identifier of the application to associate with the subscription.

​
currency
enum<string>

The currency of the subscription. Required when application is not provided.

Available options:
gbp,
usd,
eur,
sek
Example:

"gbp"

​
first_invoice_creation
enum<string> | null

Whether to create the first invoice immediately.

Available options:
immediately,
null
​
from_subscription
object

Create the subscription as a revision of an existing subscription.

​
interval_count
integer

The number of intervals between each billing cycle. Required when interval is not custom.

​
invoice_settings
object

The invoice settings for the subscription.

​
items
object[]

The items for the subscription. Required when interval is not custom.

Required array length: 1 - 10 elements
​
use_future_billing_date
boolean

Whether to use a future billing date for the first invoice.

Response

200 - application/json

Returns the subscription object if the request succeeded.

​
id
string
required

Unique identifier for the object.

​
created
number
required

Time at which the object was created. Measured in seconds since the Unix epoch.

​
object
enum<string>
required
Available options:
subscription
​
application
string | null
required

The identifier of the application associated with the subscription.

​
billing_anchor
integer | null
required

The reference point that aligns future billing cycle dates.

​
billing_anchor_config
object
required

Configuration for the billing anchor.

​
cancel_at
integer | null
required

The date at which the subscription will be automatically canceled.

​
canceled_at
integer | null
required

The date the subscription was canceled.

​
collection_method
enum<string>
required

The collection method for the subscription.

Available options:
charge_automatically,
send_invoice
​
coupon
string | null
required

The identifier of the coupon applied to the subscription.

​
currency
enum<string>
required

The currency of the subscription.

Available options:
gbp,
usd,
eur,
sek
Example:

"gbp"

​
current_period_end
integer | null
required

The end of the current billing period.

​
current_period_start
integer | null
required

The start of the current billing period.

​
custom_fields
object[]
required

Custom fields attached to the subscription invoices.

Maximum array length: 4
​
customer
required

The customer associated with the subscription.

​
days_before_collection
integer | null
required

The number of days before the due date to attempt collection.

Required range: 0 <= x <= 7
​
days_until_due
integer | null
required

The number of days until the invoice is due.

Required range: x >= 0
​
default_payment_method
string | null
required

The identifier of the default payment method for the subscription.

​
description
string | null
required

The description of the subscription.

​
end
integer | null
required

The end date of the subscription.

​
interval
enum<string>
required

The billing interval for the subscription.

Available options:
month,
week,
custom
​
interval_count
integer | null
required

The number of intervals between each billing cycle.

​
next_period_end
integer | null
required

The end of the next billing period.

​
next_period_start
integer | null
required

The start of the next billing period.

​
pause_collection
object
required

The pause collection settings for the subscription.

​
payment_settings
object
required

The payment settings for the subscription.

​
phases
object[] | null
required

The phases of the subscription.

​
start
integer
required

The start date of the subscription.

​
status
enum<string>
required

The status of the subscription.

Available options:
active,
canceled,
complete,
scheduled
​
account
string

The account that the object belongs to. Only returned if the request is made with a valid Yorlet-Context header.

​
deleted
boolean
default:false

Only returned if the object has been deleted.

​
metadata
object

Set of key-value pairs attached to the subscription.