Create a subscription

curl --request POST \
  --url https://bouclay.com/api/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customer": "<string>",
  "items": [
    {
      "priceId": "<string>",
      "price": "<string>",
      "quantity": 1,
      "planId": "<string>",
      "billingFrequency": 1,
      "quantities": {}
    }
  ],
  "paymentMethod": "<string>",
  "daysUntilDue": 182,
  "reference": "<string>",
  "requirePaymentMethod": true,
  "invoicingThreshold": 1,
  "minimumCommitment": 1,
  "discountCode": "<string>",
  "discount": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer: '<string>',
    items: [
      {
        priceId: '<string>',
        price: '<string>',
        quantity: 1,
        planId: '<string>',
        billingFrequency: 1,
        quantities: {}
      }
    ],
    paymentMethod: '<string>',
    daysUntilDue: 182,
    reference: '<string>',
    requirePaymentMethod: true,
    invoicingThreshold: 1,
    minimumCommitment: 1,
    discountCode: '<string>',
    discount: '<string>'
  })
};

fetch('https://bouclay.com/api/v1/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/subscriptions"

payload = {
    "customer": "<string>",
    "items": [
        {
            "priceId": "<string>",
            "price": "<string>",
            "quantity": 1,
            "planId": "<string>",
            "billingFrequency": 1,
            "quantities": {}
        }
    ],
    "paymentMethod": "<string>",
    "daysUntilDue": 182,
    "reference": "<string>",
    "requirePaymentMethod": True,
    "invoicingThreshold": 1,
    "minimumCommitment": 1,
    "discountCode": "<string>",
    "discount": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => '<string>',
    'items' => [
        [
                'priceId' => '<string>',
                'price' => '<string>',
                'quantity' => 1,
                'planId' => '<string>',
                'billingFrequency' => 1,
                'quantities' => [
                                
                ]
        ]
    ],
    'paymentMethod' => '<string>',
    'daysUntilDue' => 182,
    'reference' => '<string>',
    'requirePaymentMethod' => true,
    'invoicingThreshold' => 1,
    'minimumCommitment' => 1,
    'discountCode' => '<string>',
    'discount' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "id": "<string>",
    "planId": "<string>",
    "status": "<string>",
    "pauseReason": "requested",
    "pauseResumesAt": "2023-11-07T05:31:56Z",
    "currency": "<string>",
    "collectionMode": "automatic",
    "daysUntilDue": 123,
    "reference": "<string>",
    "invoicingThreshold": 1,
    "minimumCommitment": 1,
    "spendingCap": {
      "amount": 1,
      "covers": "usage",
      "behavior": "cap",
      "warnAt": [
        123
      ],
      "since": "2023-11-07T05:31:56Z"
    },
    "trialEndsAt": "2023-11-07T05:31:56Z",
    "currentPeriodStart": "2023-11-07T05:31:56Z",
    "currentPeriodEnd": "2023-11-07T05:31:56Z",
    "canceledAt": "2023-11-07T05:31:56Z",
    "endsAt": "2023-11-07T05:31:56Z",
    "cancellationDetails": {
      "reason": "<string>",
      "comment": "<string>",
      "source": "portal"
    },
    "customer": {
      "id": "<string>",
      "email": "jsmith@example.com",
      "name": "<string>",
      "taxId": "<string>"
    },
    "discount": {
      "id": "<string>",
      "code": "<string>",
      "remainingIntervals": 123
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "trialEndBehavior": "<string>",
    "paymentMethod": {
      "id": "<string>"
    },
    "items": [
      {
        "id": "<string>",
        "productId": "<string>",
        "planId": "<string>",
        "chargeId": "<string>",
        "priceId": "<string>",
        "quantity": 123,
        "status": "<string>"
      }
    ],
    "scheduledChanges": [
      {
        "action": "cancel",
        "effectiveAt": "2023-11-07T05:31:56Z",
        "itemId": "si_123",
        "quantity": 2,
        "priceId": "<string>",
        "remove": true,
        "planId": "<string>",
        "chargeId": "<string>",
        "resumesAt": "2023-11-07T05:31:56Z"
      }
    ],
    "sharedMeters": [
      {
        "meterId": "<string>",
        "meterName": "<string>",
        "subscriptionIds": [
          "<string>"
        ]
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

Subscriptions

Create a subscription

A usage charge on a meter another of the customer’s live subscriptions bills (active, past due, trialing, paused, waiting for its first payment, or with a change queued to start it) is refused with 422 meter_billed_elsewhere, whose subscriptionId and meterId name the other subscription and the meter: every event would otherwise be billed on both. A subscription that ends at or before the new charge starts doesn’t count. Plan changes and item changes refuse the same way.

POST

subscriptions

curl --request POST \
  --url https://bouclay.com/api/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customer": "<string>",
  "items": [
    {
      "priceId": "<string>",
      "price": "<string>",
      "quantity": 1,
      "planId": "<string>",
      "billingFrequency": 1,
      "quantities": {}
    }
  ],
  "paymentMethod": "<string>",
  "daysUntilDue": 182,
  "reference": "<string>",
  "requirePaymentMethod": true,
  "invoicingThreshold": 1,
  "minimumCommitment": 1,
  "discountCode": "<string>",
  "discount": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer: '<string>',
    items: [
      {
        priceId: '<string>',
        price: '<string>',
        quantity: 1,
        planId: '<string>',
        billingFrequency: 1,
        quantities: {}
      }
    ],
    paymentMethod: '<string>',
    daysUntilDue: 182,
    reference: '<string>',
    requirePaymentMethod: true,
    invoicingThreshold: 1,
    minimumCommitment: 1,
    discountCode: '<string>',
    discount: '<string>'
  })
};

fetch('https://bouclay.com/api/v1/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/subscriptions"

payload = {
    "customer": "<string>",
    "items": [
        {
            "priceId": "<string>",
            "price": "<string>",
            "quantity": 1,
            "planId": "<string>",
            "billingFrequency": 1,
            "quantities": {}
        }
    ],
    "paymentMethod": "<string>",
    "daysUntilDue": 182,
    "reference": "<string>",
    "requirePaymentMethod": True,
    "invoicingThreshold": 1,
    "minimumCommitment": 1,
    "discountCode": "<string>",
    "discount": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => '<string>',
    'items' => [
        [
                'priceId' => '<string>',
                'price' => '<string>',
                'quantity' => 1,
                'planId' => '<string>',
                'billingFrequency' => 1,
                'quantities' => [
                                
                ]
        ]
    ],
    'paymentMethod' => '<string>',
    'daysUntilDue' => 182,
    'reference' => '<string>',
    'requirePaymentMethod' => true,
    'invoicingThreshold' => 1,
    'minimumCommitment' => 1,
    'discountCode' => '<string>',
    'discount' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "id": "<string>",
    "planId": "<string>",
    "status": "<string>",
    "pauseReason": "requested",
    "pauseResumesAt": "2023-11-07T05:31:56Z",
    "currency": "<string>",
    "collectionMode": "automatic",
    "daysUntilDue": 123,
    "reference": "<string>",
    "invoicingThreshold": 1,
    "minimumCommitment": 1,
    "spendingCap": {
      "amount": 1,
      "covers": "usage",
      "behavior": "cap",
      "warnAt": [
        123
      ],
      "since": "2023-11-07T05:31:56Z"
    },
    "trialEndsAt": "2023-11-07T05:31:56Z",
    "currentPeriodStart": "2023-11-07T05:31:56Z",
    "currentPeriodEnd": "2023-11-07T05:31:56Z",
    "canceledAt": "2023-11-07T05:31:56Z",
    "endsAt": "2023-11-07T05:31:56Z",
    "cancellationDetails": {
      "reason": "<string>",
      "comment": "<string>",
      "source": "portal"
    },
    "customer": {
      "id": "<string>",
      "email": "jsmith@example.com",
      "name": "<string>",
      "taxId": "<string>"
    },
    "discount": {
      "id": "<string>",
      "code": "<string>",
      "remainingIntervals": 123
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "trialEndBehavior": "<string>",
    "paymentMethod": {
      "id": "<string>"
    },
    "items": [
      {
        "id": "<string>",
        "productId": "<string>",
        "planId": "<string>",
        "chargeId": "<string>",
        "priceId": "<string>",
        "quantity": 123,
        "status": "<string>"
      }
    ],
    "scheduledChanges": [
      {
        "action": "cancel",
        "effectiveAt": "2023-11-07T05:31:56Z",
        "itemId": "si_123",
        "quantity": 2,
        "priceId": "<string>",
        "remove": true,
        "planId": "<string>",
        "chargeId": "<string>",
        "resumesAt": "2023-11-07T05:31:56Z"
      }
    ],
    "sharedMeters": [
      {
        "meterId": "<string>",
        "meterName": "<string>",
        "subscriptionIds": [
          "<string>"
        ]
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key (rk_test_..., rk_live_...).

A secret key can call every endpoint. A restricted key can only call the endpoints its scopes cover. A scope is {resource}:{access}, for example customers:read or refunds:write, and write includes read. GET requests need read access and everything else needs write, except POST /subscriptions/{id}/items/{item}/preview, which only needs subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key is not used up.

Resource	Endpoints	Access
`customers`	customers, their addresses and payment methods	read, write
`entitlements`	`/customers/{id}/entitlements`	read
`credits`	`/customers/{id}/credit-balance`, credit purchases, credit grants, auto-reloads, credit holds (committing one records its usage)	read, write
`catalog`	products, plans, prices	read, write
`meters`	meters	read, write
`usage`	meter events, `/customers/{id}/usage`	read, write
`discounts`	discounts	read
`subscriptions`	subscriptions	read, write
`invoices`	invoices	read, write
`credit_notes`	credit notes, `POST /invoices/{id}/credit-notes` (a refund to the card also needs `refunds:write`)	read, write
`payments`	payments	read
`refunds`	refunds, `POST /payments/{id}/refunds`, chargebacks and their outcome	read, write
`checkout_sessions`	checkout sessions	read, write
`portal_sessions`	portal sessions	write
`events`	events	read
`webhook_endpoints`	webhook endpoints	read, write
`metrics`	metrics	read

Publishable keys (pk_...) are rejected by server-side API endpoints. A key's mode scopes what it can see and charge: a test key can never reach a live card.

Headers

Idempotency-Key

string

required

Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.

Required string length: 1 - 255

Body

application/json

customer

string

required

collectionMode

enum<string>

required

automatic charges a card. A subscription with something due today opens incomplete and starts on its first payment. manual sends invoices to pay by transfer or on the hosted invoice page: it opens active at once, on its payment terms (daysUntilDue), and an invoice still unpaid a day after it's due turns it past_due and is chased by reminder emails, then suspended as your dunning settings say.

Available options:

automatic,

manual

items

object[]

required

The base plan first, then add-on plans. Each plan is taken whole: a plan made of several charges goes on as one item per active charge, each at its price in one way to pay. Name it with a planId (and billingInterval when it offers several), or with one or more of its prices: the other charges are filled in with the only price each offers in that way to pay. A plan with one charge is the price given, as always. A meter is billed by one charge per subscription.

Minimum array length: 1

Show child attributes

paymentMethod

string

trialEndBehavior

enum<string>

Available options:

cancel,

pause,

create_invoice

daysUntilDue

integer | null

Payment terms for this subscription's manual invoices: each is due this many days after it's issued (0 is due on receipt). Left out, the business's payment terms apply (7 days unless changed in Billing settings, Invoicing). Manual dunning counts from the due date. Ignored for automatic collection.

Required range: 0 <= x <= 365

reference

string

The buyer's purchase order number or other reference, printed as "Your reference" on every invoice the subscription issues (PDF, hosted page, invoice and receipt emails).

Maximum string length: 100

requirePaymentMethod

boolean

Overrides the business setting for this subscription. When nothing is due at signup (every paid price is billed at the end of the period) and no paymentMethod is given, true opens the subscription incomplete behind a small card-verification invoice that is refunded once it settles; false starts it active with no card. Ignored for manual collection and free subscriptions.

On a free trial the business setting doesn't apply: a trial needs a card when its price has trialRequiresPaymentInfo, or when this is true. It then opens incomplete behind the card check and becomes trialing once the card is saved; abandoned there, it expires like any unpaid start and doesn't use up the customer's trial.

invoicingThreshold

number | null

Early access: refused until metered billing is turned on for your account.

Invoice usage early once what the subscription has used this period, and not yet been billed for, reaches this amount. Fixed fees never count toward it. The period's own invoice then bills only the rest.

Required range: x >= 0

minimumCommitment

number | null

Early access: refused until metered billing is turned on for your account.

The least the subscription bills each billing period, in major units of its currency. Fees, usage and prorations count toward it after discounts and before tax; credit the customer spends still counts. When a period bills less, the invoice that closes it adds a minimum line for the difference (with the next period's fees when the subscription bills up front, or on the final invoice when it is cancelled). A trial owes none; a period cut short by a cancellation, or paused for part of it, owes its share.

Required range: x >= 0

spendingCap

object

Early access: refused until metered billing is turned on for your account.

The most the subscription bills each billing period. Spend is what the period bills, after discounts and before tax: its usage (covers: usage, the default) or everything it bills (covers: all). A cap that stops billing (behavior: cap, the default) takes what goes past it off the invoice that bills it, with a negative maximum line; fees billed up front are always billed in full. One that only warns (behavior: warn) bills in full. At each point in warnAt (percent of the cap) your app gets spend_alert.created, once per period and cap.

Show child attributes

discountCode

string

A discount code as the customer typed it, matched without regard to case. It is redeemed onto the subscription and takes money off its invoices from the first one (after a trial, the conversion invoice). A code no discount has, or one that has expired, is switched off, is used up or doesn't cover these prices, is refused with a 422 on discountCode saying why, and nothing is created. Not with discount.

Maximum string length: 255

discount

string

A discount's id (disc_…), in place of discountCode. Refused the same way.

Response

Subscription response.

data

object

required

Show child attributes

Overview

Customers

Customer addresses

Entitlements

Credits

Usage

Payment methods

Catalog

Meters

Discounts

Subscriptions

Metrics

Invoices

Credit notes

Payments

Refunds

Chargebacks

Events

Checkout sessions

Portal sessions

Payment links

Webhook endpoints

Create a subscription

Authorizations

Headers

Body

Response