Apply Change Request

POST

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

POST

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

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

1 {
2   "change_request": {
3     "id": "cr_9f8b7a6c-1234-4d56-8e9f-0a1b2c3d4e5f",
4     "subscription_id": "sub_4d3c2b1a-5678-4e9f-8a7b-6c5d4e3f2a1b",
5     "status": "ready",
6     "item_changes_count": 2,
7     "coupon_changes_count": 1,
8     "balance_changes_count": 0,
9     "created_at": "2024-04-10T08:15:30Z",
10     "updated_at": "2024-04-12T10:45:00Z",
11     "expires_at": "2024-04-20T08:15:30Z",
12     "applied_at": null,
13     "last_preview_at": "2024-04-12T10:00:00Z",
14     "reason": "Upgrade to premium plan"
15   },
16   "result": {
17     "subscription_id": "sub_4d3c2b1a-5678-4e9f-8a7b-6c5d4e3f2a1b",
18     "new_subscriptions": [
19       "sub_7e6f5d4c-1234-4a56-9b8c-0d1e2f3a4b5c"
20     ],
21     "invoice_id": "inv_20240412_001",
22     "credit_note_id": null,
23     "payment_status": "paid",
24     "step_results": [
25       {
26         "phase": 1,
27         "action": "charge_payment",
28         "result": "success",
29         "item_id": null,
30         "new_subscription_id": null,
31         "error": null
32       },
33       {
34         "phase": 2,
35         "action": "apply_item_changes",
36         "result": "success",
37         "item_id": "item_abc123",
38         "new_subscription_id": null,
39         "error": null
40       },
41       {
42         "phase": 3,
43         "action": "apply_coupon_changes",
44         "result": "success",
45         "item_id": null,
46         "new_subscription_id": null,
47         "error": null
48       }
49     ],
50     "error": null
51   }
52 }

Apply a previewed change request.

The change request must be in ready state. Execution follows the auto-resolved order and collects payment before making any changes (Charge First pattern).

If payment fails, the subscription remains unchanged and a 402 error is returned.

Authentication

AuthorizationBearer

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

Path parameters

subscription_idstringRequired

request_idstringRequired

account_idstringRequired

Response

Successful Response

change_requestobject

Response containing a change request.

resultobject

Result of applying the change request.

Errors

402

Payment Required Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error