Change a subscription's plan

curl --request POST \
  --url https://bouclay.com/api/v1/subscriptions/{subscription}/plan-change \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "planId": "<string>",
  "priceId": "<string>",
  "billingFrequency": 2,
  "quantities": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({planId: '<string>', priceId: '<string>', billingFrequency: 2, quantities: {}})
};

fetch('https://bouclay.com/api/v1/subscriptions/{subscription}/plan-change', 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}/plan-change"

payload = {
    "planId": "<string>",
    "priceId": "<string>",
    "billingFrequency": 2,
    "quantities": {}
}
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/{subscription}/plan-change",
  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([
    'planId' => '<string>',
    'priceId' => '<string>',
    'billingFrequency' => 2,
    'quantities' => [
        
    ]
  ]),
  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"
  }
}

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

Subscriptions

Change a subscription's plan

Moves the subscription’s base plan as a whole onto another plan. The two plans’ charges are matched: a usage charge carries on onto the new plan’s charge counting the same meter, a fixed charge onto the one with the same code, and the only fixed charge left on each side pairs. Old charges with no match end (their usage so far bills on the next invoice), new ones start, and an add-on billing a meter the new plan bills ends too. Everything takes effect at one time. Made now, the rest of the period bills on one invoice; when it lowers the fixed fees, the unused time is credited by credit note. Made at the next renewal, it is one scheduled change applied before that renewal bills, replacing any plan change already pending. Two plans of one charge each change as a price swap of the item.

POST

subscriptions

{subscription}

plan-change

Change a subscription's plan

curl --request POST \
  --url https://bouclay.com/api/v1/subscriptions/{subscription}/plan-change \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "planId": "<string>",
  "priceId": "<string>",
  "billingFrequency": 2,
  "quantities": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({planId: '<string>', priceId: '<string>', billingFrequency: 2, quantities: {}})
};

fetch('https://bouclay.com/api/v1/subscriptions/{subscription}/plan-change', 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}/plan-change"

payload = {
    "planId": "<string>",
    "priceId": "<string>",
    "billingFrequency": 2,
    "quantities": {}
}
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/{subscription}/plan-change",
  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([
    'planId' => '<string>',
    'priceId' => '<string>',
    'billingFrequency' => 2,
    'quantities' => [
        
    ]
  ]),
  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"
  }
}

{
  "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

planId

string

The plan to move onto. Give this or priceId.

priceId

string

One of the plan's prices, which names the plan and the way to pay (and the price for its own charge when it has several). Not with planId, billingInterval or billingFrequency.

billingInterval

enum<string>

With planId, the way to pay. Omitted keeps the subscription's.

Available options:

day,

week,

month,

year

billingFrequency

integer

Every how many intervals. Defaults to 1, or the current interval's when only this is given.

Required range: x >= 1

quantities

object

Quantity per fixed charge of the new plan, keyed by charge id or code. A charge that carries on keeps its quantity, and a new one starts at its fewest.

Show child attributes

timing

enum<string>

Overrides the default: a change that costs the same or more in fixed fees is now, one that costs less waits for next_renewal. A longer billing interval (monthly to yearly) on a subscription of one fixed fee is now by default: the unused part of the period is credited by credit note to the balance, a new period starts today and its first invoice is charged at once, less that credit. The switch counts as the renewal: a seat count booked for the renewal is billed in the new period and used up (quantities sent with the switch replace it), and anything else booked for the renewal moves to the new one. Not while a cancel is booked: then it waits. Any other new billing interval, or a charge moving between billing at the start and at the end of the period, only works at next_renewal. While trialing, or paused off a retired plan, it is made now and bills nothing.

Available options:

now,

next_renewal

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

Change a subscription's plan

Authorizations

Headers

Path Parameters

Body

Response