Charge the next delivery now
POST /subscriptions/contracts/{contract_id}/charge| Scope | subscriptions:write |
| Customer session token | Not accepted: call from your server with an API key |
| Rate limit class | write_shopify (limits) |
| Idempotency key | Required (idempotency) |
| MCP tool | charm_charge_subscription_contract |
Bills the next unbilled cycle to the card on file today and creates the order; attempt reports how the payment went (pending until Shopify confirms, failed ones follow the shop’s retry schedule). Refused while an attempt on that cycle is still open. The real call needs confirm_charge: true, else 409 confirmation_required with the amount in details.contract.per_cycle_total.
Parameters
Section titled “Parameters”| Name | In | Type | Description |
|---|---|---|---|
contract_id | path | string | Subscription contract GID (percent-encoded) or its numeric id, as GET /subscriptions/contracts lists it. |
Request body
Section titled “Request body”| Field | Type | Description |
|---|---|---|
confirm_charge | boolean | Required, as true, on the real call. (optional) |
Response 200
Section titled “Response 200”Returns SubscriptionActionResult.
| Field | Type | Description |
|---|---|---|
action | string: skip_cycle, pause, resume, cancel, charge_now, reschedule | |
contract | SubscriptionContract | |
audit | SubscriptionAuditEntry | |
attempt | object or null | (nullable) |
cycle_index | number or null | The cycle the action worked on, for the cycle actions. (nullable) |
{ "action": "skip_cycle", "contract": { "id": "id", "numeric_id": "numeric id", "status": "active", "customer": { "id": "id", "email": "shopper@example.com" }, "plan_id": "plan id", "program_id": "program id", "frequency": { "unit": "unit", "count": 1 }, "currency": "EUR", "per_cycle_total": 1, "lines": [ { "id": null, "product_id": null, "variant_id": null, "selling_plan_id": null, "title": null, "variant_title": null, "sku": null, "quantity": null, "price": null, "discounted_price": null } ], "delivery": { "type": "earn", "city": "city", "country": "country", "zip": "zip", "option": "option", "price": 1 }, "payment_method": { "id": "id", "brand": "brand", "last_digits": "last digits", "expiry_month": 1, "expiry_year": 1 }, "next_cycle": { "index": 1, "expected_at": "2026-10-01T09:30:00.000Z" }, "cycles": [ { "index": null, "expected_at": null, "status": null, "skipped": null, "forgiven": null, "order_id": null } ], "last_attempt": { "state": "state", "error_code": "error code", "cycle_index": 1, "at": "2026-10-01T09:30:00.000Z" }, "last_order_id": "last order id", "cancel_reason": "cancel reason", "note": "note", "created_at": "2026-10-01T09:30:00.000Z", "cancelled_at": "2026-10-01T09:30:00.000Z", "paused_at": "2026-10-01T09:30:00.000Z", "updated_at": "2026-10-01T09:30:00.000Z" }, "audit": { "id": "id", "at": "2026-10-01T09:30:00.000Z", "action": "action", "actor": { "type": "earn", "id": "id", "label": "Points per order" }, "ok": false, "reason": "Goodwill after a late delivery", "correlation_id": "correlation id" }, "attempt": { "id": "id", "state": "state", "error_code": "error code" }, "cycle_index": 1}Example
Section titled “Example”curl -X POST "https://charm.appfleece.app/api/v1/subscriptions/contracts/<contract_id>/charge" \ -H "Authorization: Bearer chrm_live_..." \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"confirm_charge":true}'Errors
Section titled “Errors”unauthorized · invalid_token · insufficient_scope · access_required · not_found · validation_error · rate_limited · idempotency_conflict · shopify_unavailable
Every error body carries code, message, request_id and a doc_url pointing at the matching entry in the error catalog.