Apply Changes

POST

/api/:account_id/subscriptions/:subscription_id/change-requests/apply

POST

/api/:account_id/subscriptions/:subscription_id/change-requests/apply

$ curl -X POST https://app.paymentkit.com/api/account_id/subscriptions/subscription_id/change-requests/apply \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "change_request": {
3     "id": "cr_9f8b7a6c-1234-4d56-8e9f-abcdef123456",
4     "subscription_id": "sub_4a3b2c1d-5678-90ab-cdef-1234567890ab",
5     "status": "applied",
6     "item_changes_count": 2,
7     "coupon_changes_count": 1,
8     "balance_changes_count": 0,
9     "created_at": "2024-01-15T09:30:00Z",
10     "updated_at": "2024-01-15T10:00:00Z",
11     "expires_at": "2024-02-15T09:30:00Z",
12     "applied_at": "2024-01-15T10:05:00Z",
13     "last_preview_at": "2024-01-15T09:55:00Z",
14     "reason": "Upgrade to premium plan with discount coupon"
15   },
16   "result": {
17     "subscription_id": "sub_4a3b2c1d-5678-90ab-cdef-1234567890ab",
18     "new_subscriptions": [
19       "sub_7e6f5d4c-3210-4b98-a7c6-fedcba987654"
20     ],
21     "invoice_id": "inv_1234567890abcdef",
22     "credit_note_id": "cn_abcdef1234567890",
23     "payment_status": "paid",
24     "step_results": [
25       {
26         "phase": 1,
27         "action": "add",
28         "result": "success",
29         "item_id": "item_9876543210fedcba",
30         "new_subscription_id": "sub_7e6f5d4c-3210-4b98-a7c6-fedcba987654",
31         "error": ""
32       },
33       {
34         "phase": 2,
35         "action": "remove",
36         "result": "success",
37         "item_id": "item_1234567890abcdef",
38         "new_subscription_id": "",
39         "error": ""
40       }
41     ],
42     "error": ""
43   }
44 }

Apply subscription changes in one step.

Creates a change request, adds changes, previews, and applies — all in a single call. Supports per-item apply_at_end for deferred changes.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

subscription_idstringRequired

account_idstringRequired

Request

This endpoint expects an object.

item_changeslist of objects or nullOptional

Item changes to apply

coupon_changeslist of objects or nullOptional

Coupon changes to apply

reasonstring or nullOptional<=255 characters

Optional reason for the change

payment_method_idstring or nullOptional

Payment method ID to use (falls back to subscription default)

Response

Successful Response

change_requestobject

Response containing a change request.

resultobject

Result of applying the change request.

Errors

400

Bad Request Error

402

Payment Required Error

404

Not Found Error

422

Unprocessable Entity Error