read_chargesRequired to retrieve a charge.
write_chargesRequired to modify, skip and refund a charge.
write_paymentsThis scope is only needed when refunding a charge.
process_chargeRequired to process charges in queued status.

What is a Charge?

A charge is a placeholder for an upcoming transaction and associated line items. The corresponding order record (or orders in the case of prepaids) will be created once the charge is successful. After successful payment, the first order will be immediately submitted to the external platform if using one of our direct integrations.

Charges contain the actual amount a customer is charged for a product.

Some use cases for the Charges resource include:

  • Processing a charge
  • Finding a charge by customer, status or subscription

Charges and Subscriptions

A Charge can have many parent subscriptions. All subscriptions on a given charge scheduled_at date will be merged into one charge and that charge will show the subscription_ids referenced in the line_items block.


Delaying charge regen

Each subscription update triggers a Charge regeneration to reflect the changes made to the subscription. This can be time consuming if multiple updates are being performed in sequence. You will now be able to do it much faster using "commit_update":false in the data of your subscriptions PUT request.


For extra safety, we make sure that if the charge is processed before the regen hits, we will auto-trigger the regen before processing.

Charges FAQ

When can I use /charges/{id}/process?

The charge process resource is a Pro feature allowing a merchant to process a Charge which is either in queued or error state. See the Api Reference for further details about the resource.



In the event that a Charge has reached the maximum retry attempts defined in the store settings it can still be retried. This charge can be retried either from the merchant UI or via the API /charges/{id}/process endpoint.

Please note, certain payment provider have defined acceptable threshold for charge retries. They may reach out to you should you retry failing charges with frequencies or in volumes that they consider unreasonable.

What is the difference between created_at, scheduled_at, and processed_at?

  • created_at is when the record was created in the database
  • processed_at is when the charge was processed (paid)
  • scheduled_at is when it will be processed in the future (it is not yet processed)

What happens when a charge hits MAX_RETRIES_REACHED error ?

This happens after our system has tried to process the charge X times unsuccessfully.
Value X is defined in Admin > General settings under Failed charges section.
Our system will stop retrying to process this charge, until you manually do it via UI, or the customer’s credit card info is updated. In the meantime, the subscription will get cancelled.

Why can I sometimes see the customer IP address and sometimes not?

When a customer goes through the UI checkout, we save their 'browser IP` and store it on the charge object. The browser_ip parameter will have a value only when the customer goes through the checkout. In order to recognize these charges, look at the field type on the charge.

  • if type is equal to CHECKOUT you should see an IP
  • if type is equal to RECURRING, browser_ip will be null

If charge hits the limit of retries due to 'error' while trying to charge will it set the subscription to cancelled?

No, the customer will still have an active subscription, but it will stop retrying after the limit is reached unless the customer updates his payment information. After he updates that information it will trigger charges again for that particular subscription.

Need Help? Contact Us