Charges

Understanding charges

A charge represents an upcoming transaction and contains all 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

Scope	Description
`read_charges`	Required to retrieve a charge.
`write_charges`	Required to modify, skip and refund a charge.
`write_payments`	This scope is only needed when refunding a charge.
`process_charge`	Required to process charges in `queued` status.

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.

Charges and Subscriptions

A Charge can have many parent subscriptions. All subscriptions on a given charge scheduled_at date are merged into one charge.That charge displays the subscription_ids referenced in the line_items block.

Max_tries_reached

In the event that a Charge reaches the maximum retry attempts defined in the store settings it can still be retried, depending on your platform. This charge can be retried either from the merchant UI or via the API /charges/{id}/process endpoint. You cannot retry charges for subscriptions cancelled because they hit the number of max retries if you use the Shopify Checkout and have the Recharge When maximum number of retires are reached setting configured to an option that is not Do Nothing.

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.

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

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)

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.