Skip to content

Charge the next delivery now

POST /subscriptions/contracts/{contract_id}/charge
Scopesubscriptions:write
Customer session tokenNot accepted: call from your server with an API key
Rate limit classwrite_shopify (limits)
Idempotency keyRequired (idempotency)
MCP toolcharm_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.

NameInTypeDescription
contract_idpathstringSubscription contract GID (percent-encoded) or its numeric id, as GET /subscriptions/contracts lists it.
FieldTypeDescription
confirm_chargebooleanRequired, as true, on the real call. (optional)

Returns SubscriptionActionResult.

FieldTypeDescription
actionstring: skip_cycle, pause, resume, cancel, charge_now, reschedule
contractSubscriptionContract
auditSubscriptionAuditEntry
attemptobject or null(nullable)
cycle_indexnumber or nullThe 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
}
Terminal window
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}'

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.