Update a subscription

curl --request PATCH \
  --url https://bouclay.com/api/v1/subscriptions/{subscription} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "daysUntilDue": 182,
  "reference": "<string>",
  "invoicingThreshold": 1,
  "minimumCommitment": 1,
  "spendingCap": {
    "amount": 1,
    "warnAt": [
      80,
      100
    ]
  }
}
'

const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    daysUntilDue: 182,
    reference: '<string>',
    invoicingThreshold: 1,
    minimumCommitment: 1,
    spendingCap: {amount: 1, warnAt: [80, 100]}
  })
};

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

import requests

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

payload = {
    "daysUntilDue": 182,
    "reference": "<string>",
    "invoicingThreshold": 1,
    "minimumCommitment": 1,
    "spendingCap": {
        "amount": 1,
        "warnAt": [80, 100]
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/subscriptions/{subscription}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'daysUntilDue' => 182,
    'reference' => '<string>',
    'invoicingThreshold' => 1,
    'minimumCommitment' => 1,
    'spendingCap' => [
        'amount' => 1,
        'warnAt' => [
                80,
                100
        ]
    ]
  ]),
  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

Update a subscription

Early access. A usage threshold and a minimum commitment are metered billing: until that is turned on for your account, setting one is refused with a 422 (sending null always works). Build against it now and ask us to turn it on.

Change the settings that don’t touch the subscription’s items: the usage threshold (send null to stop invoicing early) and the minimum commitment (send null to remove it). Send one or both; a field you leave out is left as it is, and a body with neither is refused.

A minimum commitment change applies from now: the current period is held to each amount for the part of the period it was in force. A spending cap change holds the whole current period to the new cap. Invoices already issued don’t change.

PATCH

subscriptions

{subscription}

Update a subscription

curl --request PATCH \
  --url https://bouclay.com/api/v1/subscriptions/{subscription} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "daysUntilDue": 182,
  "reference": "<string>",
  "invoicingThreshold": 1,
  "minimumCommitment": 1,
  "spendingCap": {
    "amount": 1,
    "warnAt": [
      80,
      100
    ]
  }
}
'

const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    daysUntilDue: 182,
    reference: '<string>',
    invoicingThreshold: 1,
    minimumCommitment: 1,
    spendingCap: {amount: 1, warnAt: [80, 100]}
  })
};

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

import requests

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

payload = {
    "daysUntilDue": 182,
    "reference": "<string>",
    "invoicingThreshold": 1,
    "minimumCommitment": 1,
    "spendingCap": {
        "amount": 1,
        "warnAt": [80, 100]
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/subscriptions/{subscription}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'daysUntilDue' => 182,
    'reference' => '<string>',
    'invoicingThreshold' => 1,
    'minimumCommitment' => 1,
    'spendingCap' => [
        'amount' => 1,
        'warnAt' => [
                80,
                100
        ]
    ]
  ]),
  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

Path Parameters

subscription

string

required

Body

application/json

daysUntilDue

integer | null

Payment terms for manual invoices issued from now on; null goes back to the business's terms.

Required range: 0 <= x <= 365

reference

string | null

A new purchase order number for invoices issued from now on; null removes it. Invoices already issued keep theirs.

Maximum string length: 100

invoicingThreshold

number | null

Major currency units. For example, 15000 means NGN 15,000.

Required range: x >= 0

minimumCommitment

number | null

The least the subscription bills each period, in major units of its currency. null removes it.

Required range: x >= 0

spendingCap

object | null

The most the subscription bills each period. A new cap holds the whole current period, usage so far included: raised, it gives the full new room; lowered below what the period already billed, nothing more is billed (what was billed stays). Its warning points start over. null removes it. A cap on everything it bills can't be below the minimum commitment.

Show child attributes

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

Update a subscription

Authorizations

Headers

Path Parameters

Body

Response