Preview Change Request

POST

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

POST

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

$ curl -X POST https://app.paymentkit.com/api/account_id/subscriptions/subscription_id/change-requests/request_id/preview \
>      -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_4a3b2c1d-5678-4e90-9abc-1d2e3f4g5h6i",
5     "status": "draft",
6     "item_changes_count": 2,
7     "coupon_changes_count": 1,
8     "balance_changes_count": 1,
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": null,
13     "last_preview_at": "2024-01-15T10:05:00Z",
14     "reason": "Customer requested upgrade to premium plan"
15   },
16   "preview": {
17     "execution_plan": {
18       "steps": [
19         {
20           "phase": 1,
21           "action": "add_item",
22           "item_id": "item_123abc456def",
23           "price_id": "price_premium_001",
24           "quantity": 1,
25           "coupon_id": null,
26           "amount_atom": 150000
27         },
28         {
29           "phase": 2,
30           "action": "remove_item",
31           "item_id": "item_789ghi012jkl",
32           "price_id": null,
33           "quantity": null,
34           "coupon_id": null,
35           "amount_atom": -50000
36         }
37       ],
38       "auto_resolutions": [
39         {
40           "injected_action": "apply_coupon",
41           "item_id": "item_123abc456def",
42           "reason": "Auto-applied welcome discount coupon"
43         }
44       ]
45     },
46     "items_to_add": [
47       {
48         "price_id": "price_premium_001",
49         "quantity": 1
50       }
51     ],
52     "items_to_delete": [
53       "item_789ghi012jkl"
54     ],
55     "items_to_update": [
56       {
57         "item_id": "item_456mno789pqr",
58         "price_id": "price_standard_002",
59         "quantity": 2
60       }
61     ],
62     "proration_credit_atom": 50000,
63     "proration_charge_atom": 150000,
64     "invoice_total_atom": 100000,
65     "new_subscriptions": [
66       {}
67     ],
68     "original_will_cancel": false,
69     "coupon_to_add": "coupon_welcome_2024",
70     "coupon_to_remove": null,
71     "balance_to_apply_atom": 20000
72   }
73 }

Preview a change request. This computes the execution plan, detects conflicts, and calculates proration amounts without making any actual changes. The change request must be in draft or ready state. If conflicts are detected, a 422 error is returned with details about each conflict.

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.

previewobject

Preview of what the change request will do.

Errors

400

Bad Request Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error