It looks like you're using Google Chrome - try our powerful extension! Find out more. Add to Chrome
x
 

API Documentation

JSON
 

Create Charge

Creates a charge in your connected gateway and returns the created object. Add the billing support URL to invoices and receipts so you know exactly what charge a customer is asking a question about.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Parameters

using (required)
Must be set to 'card'.
customer[id] (required)
The ID of the customer you would like to charge.
Example: example@chargedesk.com
amount (required)
A string representing the amount the charge was for. This amount must be in decimal format with period (.) separating the whole and fractional parts, for example USD is displayed in the usual '29.90' format where the amount is 29 dollars and 90 cents. In German, € 1 234,56 becomes '1234.56'
Do not include the currency symbol such as $ or €
Example: 34.00
currency (required)
A 3 letter code representing the currency the charge was made in. Refer to the link below for a list of supported currency codes.
Example: USD
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
description optional
Describes what this charge is for. Can be shown on receipts and invoices.
metadata[key] optional
Set arbitrary metadata on this charge.
Refer to: https://chargedesk.com/api-docs#information-metadata
 

Request

POST https://api.chargedesk.com/v1/gateway/products/charge

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/products/charge \
  -u YOUR_SECRET_KEY: \
  -d "using=card" \
  -d "customer[id]=cus-example-QHW96q7CmS" \
  -d "amount=34.00" \
  -d "currency=USD"

Example Response

{charge: {
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}}

Create Subscription

Create a subscription for an existing customer using their card on file.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Parameters

using (required)
Must be set to 'card'.
amount (required)
A string representing the amount the charge was for. This amount must be in decimal format with period (.) separating the whole and fractional parts, for example USD is displayed in the usual '29.90' format where the amount is 29 dollars and 90 cents. In German, € 1 234,56 becomes '1234.56'
Do not include the currency symbol such as $ or €
Example: 34.00
currency (required)
A 3 letter code representing the currency the charge was made in. Refer to the link below for a list of supported currency codes.
Example: USD
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
quantity optional
The number of times this amount is applied. If provided, it must be a whole number great than 1.
Example: 2
description optional
Describes what this charge is for. Can be shown on receipts and invoices.
customer[id] (required)
If this invoice is being sent to an existing customer, this field should be used to tie the charge to that customer.
product[product_id] optional
Needs to match the ID of a product you have created or imported to ChargeDesk. Does not need to be provided if you're creating a subscription not associated with an existing product.
product[interval] (required)
Choose how frequently the subscription is charged. Possible values are day, week, month or year.
product[interval_count] optional
Default: 1
Multiplies the interval to provide a frequency for the subscription. e.g for every 6 months provide an interval_count of '6' an and interval of 'month'.
product[trial_period_days] optional
The number of days which the trial period lasts. Enter 0 for none. Must be a positive integer.
product[coupon] optional
A coupon to apply agains this product. Must match a coupon ID in your payment gateway.
product[billing_cycles_total] optional
The maximum number of billing cycles for this subscription. Enter 0 or leave blank for unlimited. Must be a positive integer. Not supported by all gateways.
product[setup_amount] optional
An additional amount to charge when the subscription is initially created. Has the same requirements as the 'amount' field.

Request

POST https://api.chargedesk.com/v1/gateway/products/charge

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/products/charge \
  -u YOUR_SECRET_KEY: \
  -d "using=card" \
  -d "customer[id]=cus-example-QHW96q7CmS" \
  -d "amount=34.00" \
  -d "currency=USD" \
  -d "product[interval]=month" \
  -d "product[trial_period_days]=14"

Example Response

{subscription: {
    amount: "34.00",
    amount_formatted: "2x $34.00 USD",
    amount_symbol: "$",
    billing_cycles_current: 1,
    billing_cycles_total: 0,
    canceled_at: 0,
    charges: 1,
    company: "company-example",
    currency: "USD",
    current_period_end: 1713449891,
    current_period_start: 1710820148,
    customer_id: "cus-example-QHW96q7CmS",
    ended_at: 0,
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    has_items: 0,
    interval: "month",
    interval_count: 1,
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/subscriptions/sub-example-cxXtztIZhh",
    metadata: {
        example_key: "Example subscription metadata"
    },
    methods_active: [
        "edit"
    ],
    methods_supported: [
        "edit"
    ],
    object: "subscription",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "Monthly",
    setup_amount: 10,
    status: "active",
    status_text: "Active",
    subscription_id: "sub-example-cxXtztIZhh",
    trial_end: 1712029748,
    trial_period_days: 14,
    trial_start: 0
}, charge: {
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}}

Request Payment

Request a payment from a customer. Can be used to create once off charges, or charges for existing products including recurring charges.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Parameters

using optional
Can be set to 'invoice' to indicate this is a payment request and not charging a card on file.
contact optional
The email address of the customer to send an invoice to. If you have activated SMS payment requests, this can be a mobile phone number. ChargeDesk will recognise phone numbers in most formats, but we recommend including a country code for reliability. If not set, a payment request page will be generated only and no email or SMS will be sent.
Example: example@chargedesk.com or +1 (555) 555-5555
link_only optional
Default: false
Generates a link to the payment page and does not automatically send an email or SMS to the contact.
amount (required)
A string representing the amount the charge was for. This amount must be in decimal format with period (.) separating the whole and fractional parts, for example USD is displayed in the usual '29.90' format where the amount is 29 dollars and 90 cents. In German, € 1 234,56 becomes '1234.56'
Do not include the currency symbol such as $ or €
Example: 34.00
currency (required)
A 3 letter code representing the currency the charge was made in. Refer to the link below for a list of supported currency codes.
Example: USD
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
quantity optional
The number of times this amount is applied. If provided, it must be a whole number great than 1.
Example: 2
description optional
Describes what this charge is for. Can be shown on receipts and invoices.
customer[id] optional
If this invoice is being sent to an existing customer, this field should be used to tie the charge to that customer.
lines[][amount] optional
A line item shown on the invoice. The amount of this line item.
lines[][currency] optional
A line item shown on the invoice. The currency of this line item.
lines[][quantity] optional
A line item shown on the invoice. The quantity of this line item. The quantity x the amount of all line items should add up to the charge amount.
lines[][product_id] optional
A line item shown on the invoice. Used to associated a line item with a product.
lines[][description] optional
A line item shown on the invoice. The description shown on the invoice for this line item.
lines[][taxable] optional
A line item shown on the invoice. Is this line item taxable?
lines[][interval] optional
A line item shown on the invoice. Only used for subscriptions. Choose how frequently the subscription is charged. Possible values are day, week, month or year.
lines[][interval_count] optional
Default: 1
A line item shown on the invoice. Only used for subscriptions. Multiplies the interval to provide a frequency for the subscription. e.g for every 6 months provide an interval_count of '6' an and interval of 'month'.
lines[][trial_period_days] optional
A line item shown on the invoice. Only used for subscriptions. The number of days which the trial period lasts. Enter 0 for none. Must be a positive integer.
lines[][coupon] optional
A line item shown on the invoice. Only used for subscriptions. A coupon to apply agains this product. Must match a coupon ID in your payment gateway.
lines[][billing_cycles_total] optional
A line item shown on the invoice. Only used for subscriptions. The maximum number of billing cycles for this subscription. Enter 0 or leave blank for unlimited. Must be a positive integer.
lines[][setup_amount] optional
A line item shown on the invoice. Only used for subscriptions. An additional amount to charge when the subscription is initially created. Has the same requirements as the 'amount' field.

Request

POST https://api.chargedesk.com/v1/gateway/products/charge

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/products/charge \
  -u YOUR_SECRET_KEY: \
  -d "contact=jane@example.com" \
  -d "amount=34.00" \
  -d "currency=USD"

Example Response

{pay_link: "https://chargedesk.com/pay/xxxxx", charge: {
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}}

Refund Charge

Process a refund for a charge. Will return a success of failure from the originating payment gateway.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Parameters

amount optional
A partial amount you wish to refund on the charge. If not provided, the full amount of the charge will be refunded.
Example: 21.00
log_reason optional
Provide a reason to be logged in the activity log this refund

Request

POST https://api.chargedesk.com/v1/gateway/charges/{CHARGE_ID}/refund

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/charges/example-8p1KDdjbM0EGhRFncTstwYBB/refund \
  -u YOUR_SECRET_KEY: \
  -d "amount=21.00"

Example Response

{
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "21.00",
    amount_refunded_formatted: "$21.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "refund notification",
    name_send_email: "Send Refund Notification",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "partially refunded",
    status_text: "partially refunded",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}

Capture Charge

Capture or void an authorized charge. Will return a success of failure from the originating payment gateway.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Parameters

amount optional
An amount you wish to capture on the charge. If not provided, the full amount of the authorized charge will be captured. If set to 0, the authorized charge will be voided.
Example: 21.00

Request

POST https://api.chargedesk.com/v1/gateway/charges/{CHARGE_ID}/capture

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/charges/example-8p1KDdjbM0EGhRFncTstwYBB/capture \
  -u YOUR_SECRET_KEY: \
  -d "amount=34.00"

Example Response

{
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}

Cancel Subscription

Cancels any future recurring charges through original payment gateway it was created. May not be supported on all gateways.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Parameters

log_reason optional
Provide a reason to be logged in the activity log this refund

Request

POST https://api.chargedesk.com/v1/gateway/subscriptions/{SUBSCRIPTION_ID}/cancel

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/subscriptions/sub-example-cxXtztIZhh/cancel \
  -u YOUR_SECRET_KEY: \
  -X POST

Example Response

{
    amount: "34.00",
    amount_formatted: "2x $34.00 USD",
    amount_symbol: "$",
    billing_cycles_current: 1,
    billing_cycles_total: 0,
    canceled_at: 0,
    charges: 1,
    company: "company-example",
    currency: "USD",
    current_period_end: 1713449891,
    current_period_start: 1710820148,
    customer_id: "cus-example-QHW96q7CmS",
    ended_at: 0,
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    has_items: 0,
    interval: "month",
    interval_count: 1,
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/subscriptions/sub-example-cxXtztIZhh",
    metadata: {
        example_key: "Example subscription metadata"
    },
    methods_active: [],
    methods_supported: [
        "edit"
    ],
    object: "subscription",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "Monthly",
    setup_amount: 10,
    status: "canceled",
    status_text: "Canceled",
    subscription_id: "sub-example-cxXtztIZhh",
    trial_end: 1712029748,
    trial_period_days: 14,
    trial_start: 0
}

Edit Subscription Plans

Edits a subscription's plans and recurring details. Not be supported on all gateways.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Parameters

plans[][id] optional
The ID of a plans to save to the subscription. Leave the plans parameter empty if you do not want to edit a subscriptions plans. Stripe & Recurly only.
plans[][quantity] optional
The quantity of the plan to save to the subscription. Leave the plans parameter empty if you do not want to edit a subscriptions plans. Stripe & Recurly only.
trial_end optional
Unix timestamp for when the subscription's trial ends. Stripe only.
Example: 1710820148
period_end optional
Unix timestamp for when the subscription's current period ends. Recurly only.
Example: 1710820148
prorate optional
Prorate any plans changes. Stripe only.
Example: true
invoice optional
Invoice any plans changes immediately instead of at period end. Stripe & Recurly only.
Example: true

Request

POST https://api.chargedesk.com/v1/gateway/subscriptions/{SUBSCRIPTION_ID}/plans

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/subscriptions/sub-example-cxXtztIZhh/plans \
  -u YOUR_SECRET_KEY: \
  -X POST

Example Response

{
    amount: "34.00",
    amount_formatted: "2x $34.00 USD",
    amount_symbol: "$",
    billing_cycles_current: 1,
    billing_cycles_total: 0,
    canceled_at: 0,
    charges: 1,
    company: "company-example",
    currency: "USD",
    current_period_end: 1713449891,
    current_period_start: 1710820148,
    customer_id: "cus-example-QHW96q7CmS",
    ended_at: 0,
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    has_items: 0,
    interval: "month",
    interval_count: 1,
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/subscriptions/sub-example-cxXtztIZhh",
    metadata: {
        example_key: "Example subscription metadata"
    },
    methods_active: [
        "edit"
    ],
    methods_supported: [
        "edit"
    ],
    object: "subscription",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "Monthly",
    setup_amount: 10,
    status: "active",
    status_text: "Active",
    subscription_id: "sub-example-cxXtztIZhh",
    trial_end: 1712029748,
    trial_period_days: 14,
    trial_start: 0
}

Cancel Payment Request

Cancel the payment request. The payment page will show that the charge no longer needs to be paid.

This is a gateway method. This means that the status of this resource will be updated on gateway it originated from as well as on ChargeDesk. May not be supported on all gateways.

Request

POST https://api.chargedesk.com/v1/gateway/charges/{CHARGE_ID}/void

Example Curl Command

curl https://api.chargedesk.com/v1/gateway/charges/example-8p1KDdjbM0EGhRFncTstwYBB/void \
  -u YOUR_SECRET_KEY: \
  -X POST

Example Response

{
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}

Create

Creates a record of an external charge. NB: this is not a gateway method, so will not create a live charge on your gateway. Use the Create Charge gateway method to create a live charge.

Parameters

amount (required)
A string representing the amount the charge was for. This amount must be in decimal format with period (.) separating the whole and fractional parts, for example USD is displayed in the usual '29.90' format where the amount is 29 dollars and 90 cents. In German, € 1 234,56 becomes '1234.56'
Do not include the currency symbol such as $ or €
Example: 34.00
currency (required)
A 3 letter code representing the currency the charge was made in. Refer to the link below for a list of supported currency codes.
Example: USD
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
gateway_id optional
The id of gateway which this charge occurred through. Will be set to the default gateway associated with your account if not provided. You can find the gateway id associated with a gateway on the setup page for your company.
Example: stripe
occurred optional
Default: The current time since epoch will be used.
The time in seconds since epoch when the charge was made (unix timestamp). This can be used to import charges that occurred in the past into ChargeDesk. Must be equal to or less than current time since epoch.
Example: 1361191994
customer[id] (required)
A unique string which all charges from the same customer share. This could be an email address, username or user id.
Example: example@chargedesk.com
customer[email] optional
Email address of the customer who this charge is for. Optional, but highly recommended. If an email address is used for the customer[id], and no other address is provided, this field will be automatically populated with the customer[id].
customer[username] optional
The username this customer users to login into your system. Optional, but highly recommended. If not provided, the customer[email] value will be used if available.
customer[name] optional
Full name of the customer who this charge is for.
Example: James Peter
customer[description] optional
Some additional information useful in describing this customer to support agents.
customer[delinquent] optional
Default: false
Is there a problem with the payments of this customer not being processed?
customer[country] optional
Two-letter ISO code of the country where the customer is located.
Example: US
status optional
Default: paid
The current state of this charge. Can be 'pending', 'paid', 'partially refunded', 'refunded', 'failed', 'authorized', 'void', 'invoiced', 'invoice canceled', 'unpaid', 'past due', 'subscription pending', 'disputed', 'trial', 'credit', 'uncollectible', 'open' or 'draft'.
amount_refunded optional
A string representing how much of the charge has been refunded if partially refunded. This amount must be in decimal format with the same conditions as the 'amount' parameter.
Example: 24.50
last_4_digits optional
Last 4 digits of the credit card used to create this charge.
transaction_id optional
A unique string of your choice that can be used to identify this transaction in your system/gateway. You can use it as an identifier to know when a charge has been refunded through a webhook.
duplicate optional
If an existing charge with a matching transaction_id already exists, setting duplicate to 'update' allows the API request to not fail. Instead it will update the existing charge with any new data.
Example: update
Refer to: https://chargedesk.com/api-docs#information-handling-duplicates
description optional
A short string describing what this charge is for. Displayed to users when they are querying why a charge was made.
product[id] optional
An identifier which ties all charges for the same product together. Used to provide additional information to the customer about what the charge was for.
subscription[id] optional
Used to identify recurring charges. All charges for a subscription should share the same subscription id. Required if providing a subscription in a charge.
lines[][amount] optional
A line item shown on the invoice. The amount of this line item.
lines[][currency] optional
A line item shown on the invoice. The currency of this line item.
lines[][quantity] optional
A line item shown on the invoice. The quantity of this line item. The quantity x the amount of all line items should add up to the charge amount.
lines[][product_id] optional
A line item shown on the invoice. Used to associated a line item with a product.
lines[][description] optional
A line item shown on the invoice. The description shown on the invoice for this line item.
lines[][taxable] optional
A line item shown on the invoice. Is this line item taxable?
lines[][tax_paid] optional
A line item shown on the invoice. If this charge has been paid, this is the amount of tax associated with this line item.
metadata[key] optional
Set arbitrary metadata on this charge.
Refer to: https://chargedesk.com/api-docs#information-metadata

Request

POST https://api.chargedesk.com/v1/charges

Example Curl Command

curl https://api.chargedesk.com/v1/charges \
  -u YOUR_SECRET_KEY: \
  -d "amount=34.00" \
  -d "currency=USD" \
  -d "customer[id]=cus-example-QHW96q7CmS"

Example Response

{
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}

List all

Get all charges associated with the secret key provided in the request

Parameters

count optional
Default: 20
Number of charges to return per request in the response. Must be between 1 and 500.
offset optional
Default: 0
Position to start returning charges from. Used to paginate through all charges. Must be between 0 and 50,000. We recommend using occurred[max] to paginate earlier than 50,000 charges.
status optional
Only return charges in a certain state. Can be 'pending', 'paid', 'partially refunded', 'refunded', 'failed', 'authorized', 'void', 'invoiced', 'invoice canceled', 'unpaid', 'past due', 'subscription pending', 'disputed', 'trial', 'credit', 'uncollectible', 'open' or 'draft'
query optional
Only return charges which match the given query. The query will run against any searchable field.
customer[id] optional
Only return charges from customers matching this customer id.
customer[email] optional
Only return charges from customers matching this email.
customer[name] optional
Only return charges from customers matching this name.
customer[username] optional
Only return charges from customers matching this username.
last_4_digits optional
Only return charges with customers matching these last 4 digits on their card.
description optional
Only return charges with customers matching this description.
transaction_id optional
Only return charges which match this gateway transaction id. This will be the same as the invoice number or charge id from your payment gateway.
occurred[max] optional
Maximum seconds since epoch (unix timestamp) that charges must have occurred before.
occurred[min] optional
Minimum seconds since epoch (unix timestamp) that charges must have occurred after.
metadata_key optional
Only return charges which have metadata with this key.
metadata_value optional
Only return charges which have metadata with this value.

Request

GET https://api.chargedesk.com/v1/charges

Example Curl Command

curl https://api.chargedesk.com/v1/charges?count=2 \
  -u YOUR_SECRET_KEY:

Example Response

{
    "count": 2,
    "offset": 0,
    "data": [
{
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
},
... more data items here ...
    ]
}

Retrieve

Retrieves a charge that has previously been created.

Request

GET https://api.chargedesk.com/v1/charges/{CHARGE_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/charges/example-8p1KDdjbM0EGhRFncTstwYBB \
  -u YOUR_SECRET_KEY:

Example Response

{
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}

Update

Updates an existing charge with new information.

Parameters

amount optional
A string representing the amount the charge was for. This amount must be in decimal format with period (.) separating the whole and fractional parts, for example USD is displayed in the usual '29.90' format where the amount is 29 dollars and 90 cents. In German, € 1 234,56 becomes '1234.56'
Do not include the currency symbol such as $ or €
Example: 34.00
currency optional
A 3 letter code representing the currency the charge was made in. Refer to the link below for a list of supported currency codes.
Example: USD
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
occurred optional
Default: The current time since epoch will be used.
The time in seconds since epoch when the charge was made (unix timestamp). This can be used to import charges that occurred in the past into ChargeDesk. Must be equal to or less than current time since epoch.
Example: 1361191994
customer[id] (required)
A unique string which all charges from the same customer share. This could be an email address, username or user id.
Example: example@chargedesk.com
customer[email] optional
Email address of the customer who this charge is for. Optional, but highly recommended. If an email address is used for the customer[id], and no other address is provided, this field will be automatically populated with the customer[id].
customer[username] optional
The username this customer users to login into your system. Optional, but highly recommended. If not provided, the customer[email] value will be used if available.
customer[name] optional
Full name of the customer who this charge is for.
Example: James Peter
customer[description] optional
Some additional information useful in describing this customer to support agents.
customer[delinquent] optional
Default: false
Is there a problem with the payments of this customer not being processed?
customer[country] optional
Two-letter ISO code of the country where the customer is located.
Example: US
status optional
Default: paid
The current state of this charge. Can be 'pending', 'paid', 'partially refunded', 'refunded', 'failed', 'authorized', 'void', 'invoiced', 'invoice canceled', 'unpaid', 'past due', 'subscription pending', 'disputed', 'trial', 'credit', 'uncollectible', 'open' or 'draft'.
amount_refunded optional
A string representing how much of the charge has been refunded if partially refunded. This amount must be in decimal format with the same conditions as the 'amount' parameter.
Example: 24.50
last_4_digits optional
Last 4 digits of the credit card used to create this charge.
transaction_id optional
A unique string of your choice that can be used to identify this transaction in your system. You can use it as an identifier to know when a charge has been refunded through a webhook.
description optional
A short string describing what this charge is for. Displayed to users when they are querying why a charge was made.
product[id] optional
An identifier which ties all charges for the same product together. Used to provide additional information to the customer about what the charge was for.
subscription[id] optional
Used to identify recurring charges. All charges for a subscription should share the same subscription id. Required if providing a subscription in a charge.
lines[][amount] optional
A line item shown on the invoice. The amount of this line item.
lines[][currency] optional
A line item shown on the invoice. The currency of this line item.
lines[][quantity] optional
A line item shown on the invoice. The quantity of this line item. The quantity x the amount of all line items should add up to the charge amount.
lines[][product_id] optional
A line item shown on the invoice. Used to associated a line item with a product.
lines[][description] optional
A line item shown on the invoice. The description shown on the invoice for this line item.
lines[][taxable] optional
A line item shown on the invoice. Is this line item taxable?
lines[][tax_paid] optional
A line item shown on the invoice. If this charge has been paid, this is the amount of tax associated with this line item.
metadata[key] optional
Set arbitrary metadata on this charge.
Refer to: https://chargedesk.com/api-docs#information-metadata

Request

POST https://api.chargedesk.com/v1/charges/{CHARGE_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/charges/example-8p1KDdjbM0EGhRFncTstwYBB \
  -u YOUR_SECRET_KEY: \
  -d "status=paid"

Example Response

{
    added_tax: "0.00",
    amount: "34.00",
    amount_formatted: "$34.00 USD",
    amount_refunded: "0.00",
    amount_refunded_formatted: "$0.00 USD",
    amount_symbol: "$",
    amount_with_commas: "34.00",
    charge_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    company: "company-example",
    currency: "USD",
    customer_country: "US",
    customer_email: "jane@example.com",
    customer_id: "cus-example-QHW96q7CmS",
    customer_name: "Jane Customer",
    customer_phone: null,
    customer_username: "janecustomer",
    description: "An example charge",
    email_last_sent: 0,
    gateway_id: "",
    gateway_url: "",
    invoice_company: null,
    invoice_download_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice/download",
    invoice_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB/invoice",
    is_paid: true,
    last_4_digits: "1234",
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/charges/example-8p1KDdjbM0EGhRFncTstwYBB",
    metadata: {
        example_key: "Example charge metadata"
    },
    methods_active: [
        "email"
    ],
    methods_supported: [
        "edit",
        "remind",
        "email"
    ],
    name_email: "receipt",
    name_send_email: "Send Receipt",
    object: "charge",
    occurred: 1710820148,
    occurred_formatted: "moments ago",
    occurred_relative: "moments ago",
    payment_method: "Credit",
    payment_method_brand: "Visa",
    payment_method_describe: "Visa credit card",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    refunded_at_formatted: "",
    sent_invoice: "",
    sent_invoice_reminder: "",
    status: "paid",
    status_text: "paid",
    subscription_id: "sub-example-cxXtztIZhh",
    support_email: "company-example+example-8p1KDdjbM0EGhRFncTstwYBB@chargedesk.com",
    support_url: "https://chargedesk.com/company-example/example-8p1KDdjbM0EGhRFncTstwYBB",
    transaction_id: "transaction-example-a7sMG9VqJg"
}

Email Charge

Send an email notification (such as receipt) to the customer. The type of email sent will depend on the current status of the charge. Paid or Pending charges will send a receipt. Refunded charges will send a refund notification. Authorized charges will send an authorized notification. Voided charges will send a void email.

Parameters

email optional
The email address to send the notification to.
Example: example@customer.com

Request

POST https://api.chargedesk.com/v1/charges/{CHARGE_ID}/email

Example Curl Command

curl https://api.chargedesk.com/v1/charges/example-8p1KDdjbM0EGhRFncTstwYBB/email \
  -u YOUR_SECRET_KEY: \
  -d "email=example@customer.com"

Preview Charge

Preview the subtotal, any tax rates and the final total amount for a charge or product. Calculations are based on the country and tax ID provided. Useful for previews in checkout forms.

Parameters

charge_id optional
The charge to preview.
product_id optional
The product to preview. Ignored if a charge_id is also provided.
amount optional
The amount to preview. Required if no charge or product is provided, otherwise will override the amount for the charge or product.
currency optional
The currency to preview. Required if no charge or product is provided, otherwise will override the currency for the charge or product.
country optional
Two-letter ISO code of the country where the customer is located.
Example: US
tax_number optional
Tax ID. This is an alphanumeric tax identification for the customer. It is used to determine if the invoice should have 0% tax applied.
Example: 123 123 1234
add_tax optional
Override the company setting for if tax is added to the final amount, or included in it.

Request

GET https://api.chargedesk.com/v1/charges/preview

Example Curl Command

curl https://api.chargedesk.com/v1/charges/preview?charge_id=example-8p1KDdjbM0EGhRFncTstwYBB&amount=10.00&currency=USD&country=US \
  -u YOUR_SECRET_KEY:

Example Response

{
    "subtotalAmount": 10,
    "subtotalAmountFormatted": "$10.00",
    "taxRates": [
        {
            "name": "Tax",
            "rate": 10,
            "amount": 1,
            "amountFormatted": "$1.00"
        }
    ],
    "totalAmount": 11,
    "totalAmountFormatted": "$11.00"
}

Delete

Deletes a charge record.

Request

DELETE https://api.chargedesk.com/v1/charges/{CHARGE_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/charges/example-8p1KDdjbM0EGhRFncTstwYBB \
  -u YOUR_SECRET_KEY: \
  -X DELETE

Create

Used to tie all charges from the same person together.

Parameters

customer_id (required)
A unique string which all charges from the same customer share. This could be an email address, username or user id.
Example: cus-example
duplicate optional
If an existing customer with a matching customer_id already exists, setting duplicate to 'update' allows the API request to not fail. Instead it will update the existing customer with any new data.
Example: update
Refer to: https://chargedesk.com/api-docs#information-handling-duplicates
gateway_id optional
The id of gateway associated with the customer. You can find the gateway id associated with a gateway on the setup page for your company.
Example: stripe
email optional
Email address of the customer who this charge is for. Optional, but highly recommended.
country optional
Two-letter ISO code of the country where the customer is located.
Example: US
name optional
Full name of the customer who this charge is for.
Example: Jane Customer
phone optional
The full international phone number for the customer. The international prefix for the phone number should be included (e.g. +1), if not included it will attempted to be calculated using the provided customer's country code.
Example: +1 (555) 555-5555
username optional
A username associated with this customer.
Example: janecustomer
customer_company optional
A company name or ID associated with the customer.
website optional
A website associated with the customer.
description optional
A description of up to 255 characters for the customer.
delinquent optional
Is the customer past due on their payments?
Example: false
card_on_file optional
Does the customer have a card on file which can be charged?
Example: true
tax_number_abr optional
Tax ID Abbreviation. Generally 3-4 letters such as GST or VAT.
Example: VAT
tax_number optional
Tax ID. This is an alphanumeric tax identification for the customer. It is listed on invoices in the case of VAT can be used to determine if the invoice should have 0% tax applied.
Example: 123 123 1234
billing_address optional
The full billing address for the customer. Used on invoices if the invoice address is not provided. It can be formatted in multiple lines and must be less than up to 255 characters.
Example: 12 Billing Street London, United Kingdom
shipping_address optional
The full shipping address for the customer. It can be formatted in multiple lines and must be less than up to 255 characters.
Example: 12 Shipping Street London, United Kingdom
invoice_details optional
This is generally the full address for the customer, as listed on invoices. If not provided, the billing address will be used on invoices. It can be formatted in multiple lines and must be less than up to 255 characters.
Example: 12 Invoice Street London, United Kingdom
metadata[key] optional
Set arbitrary metadata on this customer.
Refer to: https://chargedesk.com/api-docs#information-metadata

Request

POST https://api.chargedesk.com/v1/customers

Example Curl Command

curl https://api.chargedesk.com/v1/customers \
  -u YOUR_SECRET_KEY: \
  -d "customer_id=cus-example-QHW96q7CmS" \
  -d "country=US"

Example Response

{
    billing_address: "123 Example Street\nExample City\nExample State, United States, 90000",
    charges: 0,
    company: "company-example",
    country: "US",
    customer_company: "Example Company LTD",
    customer_id: "cus-example-QHW96q7CmS",
    delinquent: 0,
    description: "An example customer",
    edited: 0,
    email: "jane@example.com",
    first_name: "Jane",
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    invoice_details: "",
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-QHW96q7CmS",
    metadata: {
        example_key: "Example customer metadata"
    },
    methods_active: [
        "invoice",
        "edit"
    ],
    methods_supported: [
        "invoice",
        "edit"
    ],
    name: "Jane Customer",
    object: "customer",
    phone: "+1 555-555-5555",
    readable_country: "United States",
    shipping_address: "",
    subscriptions: [],
    tax_number: "123456789",
    tax_number_abr: "VAT",
    username: "janecustomer",
    website: "https://example.com"
}

List all

Get all customers associated with the secret key provided in the request

Parameters

count optional
Default: 20
Number of customers to return per request in the response. Must be between 1 and 500.
offset optional
Default: 0
Position to start returning customers from. Used to paginate through all customers. Must be between 0 and 50,000. We recommend using first_seen[max] to paginate earlier than 50,000 customers.
customer_id optional
Only return customers matching this customer id.
email optional
Only return customers matching this email.
name optional
Only return customers matching this name.
username optional
Only return customers matching this username.
country optional
Only return customers matching this country.
first_seen[max] optional
Maximum seconds since epoch (unix timestamp) that customer must have been created before.
first_seen[min] optional
Minimum seconds since epoch (unix timestamp) that customer must have been created after.

Request

GET https://api.chargedesk.com/v1/customers

Example Curl Command

curl https://api.chargedesk.com/v1/customers?count=2 \
  -u YOUR_SECRET_KEY:

Example Response

{
    "count": 2,
    "offset": 0,
    "data": [
{
    billing_address: "123 Example Street\nExample City\nExample State, United States, 90000",
    charges: 0,
    company: "company-example",
    country: "US",
    customer_company: "Example Company LTD",
    customer_id: "cus-example-QHW96q7CmS",
    delinquent: 0,
    description: "An example customer",
    edited: 0,
    email: "jane@example.com",
    first_name: "Jane",
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    invoice_details: "",
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-QHW96q7CmS",
    metadata: {
        example_key: "Example customer metadata"
    },
    methods_active: [
        "invoice",
        "edit"
    ],
    methods_supported: [
        "invoice",
        "edit"
    ],
    name: "Jane Customer",
    object: "customer",
    phone: "+1 555-555-5555",
    readable_country: "United States",
    shipping_address: "",
    subscriptions: [],
    tax_number: "123456789",
    tax_number_abr: "VAT",
    username: "janecustomer",
    website: "https://example.com"
},
... more data items here ...
    ]
}

Retrieve

Retrieves a customer that has previously been created.

Request

GET https://api.chargedesk.com/v1/customers/{CUSTOMER_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/customers/cus-example-QHW96q7CmS \
  -u YOUR_SECRET_KEY:

Example Response

{
    billing_address: "123 Example Street\nExample City\nExample State, United States, 90000",
    charges: 0,
    company: "company-example",
    country: "US",
    customer_company: "Example Company LTD",
    customer_id: "cus-example-QHW96q7CmS",
    delinquent: 0,
    description: "An example customer",
    edited: 0,
    email: "jane@example.com",
    first_name: "Jane",
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    invoice_details: "",
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-QHW96q7CmS",
    metadata: {
        example_key: "Example customer metadata"
    },
    methods_active: [
        "invoice",
        "edit"
    ],
    methods_supported: [
        "invoice",
        "edit"
    ],
    name: "Jane Customer",
    object: "customer",
    phone: "+1 555-555-5555",
    readable_country: "United States",
    shipping_address: "",
    subscriptions: [],
    tax_number: "123456789",
    tax_number_abr: "VAT",
    username: "janecustomer",
    website: "https://example.com"
}

Update

Update the data stored for an existing customer.

Parameters

customer_id optional
A unique string which all charges from the same customer share. If a new value is provided here, this should then be used as the {CUSTOMER_ID} for future requests.
Example: cus-example
gateway_id optional
The id of gateway associated with the customer. You can find the gateway id associated with a gateway on the setup page for your company.
Example: stripe
override_agents optional
Default: false
Overrides any edits made manually by support agents. If not set, API updates will be ignored if the field was previously edited by a support agent.
email optional
Email address of the customer who this charge is for. Optional, but highly recommended.
send_email_to optional
Overrides the primary email address associated with the customer for the purposes of email delivery. If set, receipts and other email notifications will be sent to this address instead of the primary email address for the customer. Accepts multiple email addresses seperated by a comma.
country optional
Two-letter ISO code of the country where the customer is located.
Example: US
name optional
Full name of the customer who this charge is for.
Example: Jane Customer
phone optional
The full international phone number for the customer. The international prefix for the phone number should be included (e.g. +1), if not included it will attempted to be calculated using the provided customer's country code.
Example: +1 (555) 555-5555
username optional
A username associated with this customer.
Example: janecustomer
customer_company optional
A company name or ID associated with the customer.
website optional
A website associated with the customer.
description optional
A description of up to 255 characters for the customer.
delinquent optional
Is the customer past due on their payments?
Example: false
card_on_file optional
Does the customer have a card on file which can be charged?
Example: true
tax_number_abr optional
Tax ID Abbreviation. Generally 3-4 letters such as GST or VAT.
Example: VAT
tax_number optional
Tax ID. This is an alphanumeric tax identification for the customer. It is listed on invoices in the case of VAT can be used to determine if the invoice should have 0% tax applied.
Example: 123 123 1234
billing_address optional
The full billing address for the customer. Used on invoices if the invoice address is not provided. It can be formatted in multiple lines and must be less than up to 255 characters.
Example: 12 Billing Street London, United Kingdom
shipping_address optional
The full shipping address for the customer. It can be formatted in multiple lines and must be less than up to 255 characters.
Example: 12 Shipping Street London, United Kingdom
invoice_details optional
This is generally the full address for the customer, as listed on invoices. If not provided, the billing address will be used on invoices. It can be formatted in multiple lines and must be less than up to 255 characters.
Example: 12 Invoice Street London, United Kingdom
metadata[key] optional
Set arbitrary metadata on this customer.
Refer to: https://chargedesk.com/api-docs#information-metadata

Request

POST https://api.chargedesk.com/v1/customers/{CUSTOMER_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/customers/cus-example-QHW96q7CmS \
  -u YOUR_SECRET_KEY: \
  -d "username=janecustomer"

Example Response

{
    billing_address: "123 Example Street\nExample City\nExample State, United States, 90000",
    charges: 0,
    company: "company-example",
    country: "US",
    customer_company: "Example Company LTD",
    customer_id: "cus-example-QHW96q7CmS",
    delinquent: 0,
    description: "An example customer",
    edited: 0,
    email: "jane@example.com",
    first_name: "Jane",
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    invoice_details: "",
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-QHW96q7CmS",
    metadata: {
        example_key: "Example customer metadata"
    },
    methods_active: [
        "invoice",
        "edit"
    ],
    methods_supported: [
        "invoice",
        "edit"
    ],
    name: "Jane Customer",
    object: "customer",
    phone: "+1 555-555-5555",
    readable_country: "United States",
    shipping_address: "",
    subscriptions: [],
    tax_number: "123456789",
    tax_number_abr: "VAT",
    username: "janecustomer",
    website: "https://example.com"
}

Grouped

Gets the structured billing history for a customer. Used for assisting agents to solve support requests. As much data as possible should be provided for most accurate results.

Parameters

customer[id] optional
Looks for customers & charges matching this id
customer[email] optional
Looks for customers & charges matching this email.
customer[username] optional
Looks for customers & charges matching this username.
customer[name] optional
Looks for customers & charges matching this name.
customer[phone] optional
Looks for customers & charges matching this phone number.
query optional
A text string to find matching customers & charges. Can be a name, email address, username, phone number or last 4 digits of a credit card. If provided, the other parameters are ignored.

Request

GET https://api.chargedesk.com/v1/customers/grouped

Example Curl Command

curl https://api.chargedesk.com/v1/customers/grouped?customer%5Bemail%5D=james%40example.com \
  -u YOUR_SECRET_KEY:

Delete

Deletes a customer record.

Parameters

delete_all optional
Default: 1
Delete all data associated with a customer, such as charges and tickets (useful for GDPR compliance). If set to 0, only the customer record itself will be deleted. If set to 2, delete the customer record, but keep anonymised charges and subscriptions.

Request

DELETE https://api.chargedesk.com/v1/customers/{CUSTOMER_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/customers/cus-example-QHW96q7CmS \
  -u YOUR_SECRET_KEY: \
  -X DELETE

Create

Creates a record of an external subscription. NB: this is not a gateway method, so will not create a live subscription on your gateway. Use the Create Subscription gateway method to create a live subscription.

Parameters

subscription_id (required)
Used to identify recurring charges. All charges for a subscription should share the same subscription id. Sent back in webhooks when subscriptions are modified.
duplicate optional
If an existing subscription with a matching subscription_id already exists, setting duplicate to 'update' allows the API request to not fail. Instead it will update the existing subscription with any new data.
Example: update
Refer to: https://chargedesk.com/api-docs#information-handling-duplicates
customer_id optional
The ID of the customer that this subscription is associated with.
status optional
Default: active
The current status of this subscription. Possible values are 'requested', 'pending' (will transition to active), 'new' (awaiting payment method), 'trialing', 'active', 'past_due', 'canceled', 'unpaid', 'suspended' (can be reactivated at any time) or 'pending_cancel' (will be canceled at current period's end).
gateway_id optional
The id of gateway which this subscription occurred through. Will be set to the default gateway associated with your account if not provided. You can find the gateway id associated with a gateway on the setup page for your company.
Example: stripe
amount optional
The amount that this subscription is for. Must be a decimal value.
currency optional
The currency that this subscription uses.
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
setup_amount optional
Additional amount charged when subscription is first created. Must be a decimal value.
product_id optional
If defined, needs to match the ID of a product you have created or imported to ChargeDesk.
interval optional
How frequently the subscription is charged. Possible values are day, week, month or year.
Example: month
interval_count optional
How frequently the subscription is charged - combine with interval to define freqency. e.g. a fornightly subscription would have an interval of 'week' and an interval_count of '2'
Example: 6
quantity optional
The number of times this amount is applied. If provided, it must be a whole number great than 1.
Example: 2
current_period_start optional
When the current billing cycle started. In seconds since epoch (unix timestamp).
Example: 1710820148
current_period_end optional
When the current billing cycle will end. In seconds since epoch (unix timestamp).
Example: 1710820148
trial_start optional
When the trial period started (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1710820148
trial_end optional
When the trial period will end (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1710820148
ended_at optional
When the subscription ended (if not cancelled). In seconds since epoch (unix timestamp).
Example: 1710820148
canceled_at optional
When the subscription was cancelled. In seconds since epoch (unix timestamp).
Example: 1710820148
billing_cycles_total optional
Total number of billing cycles for this subscription.
Example: 10
billing_cycles_current optional
Current billing cycle for this subscription.
Example: 2
items[][id] optional
The ID of this subscription item.
items[][amount] optional
The amount of this subscription item.
items[][currency] optional
The currency of this subscription item.
items[][quantity] optional
The quantity of this subscription item.
items[][percent] optional
If the subscription item represents a discount, this defines the percentage discount.
items[][description] optional
The description of this subscription item.
metadata[key] optional
Set arbitrary metadata on this subscription.
Refer to: https://chargedesk.com/api-docs#information-metadata

Request

POST https://api.chargedesk.com/v1/subscriptions

Example Curl Command

curl https://api.chargedesk.com/v1/subscriptions \
  -u YOUR_SECRET_KEY: \
  -d "subscription_id=sub-example-cxXtztIZhh" \
  -d "customer_id=cus-example-QHW96q7CmS" \
  -d "amount=34.00" \
  -d "currency=USD" \
  -d "interval=month"

Example Response

{
    amount: "34.00",
    amount_formatted: "2x $34.00 USD",
    amount_symbol: "$",
    billing_cycles_current: 1,
    billing_cycles_total: 0,
    canceled_at: 0,
    charges: 1,
    company: "company-example",
    currency: "USD",
    current_period_end: 1713449891,
    current_period_start: 1710820148,
    customer_id: "cus-example-QHW96q7CmS",
    ended_at: 0,
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    has_items: 0,
    interval: "month",
    interval_count: 1,
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/subscriptions/sub-example-cxXtztIZhh",
    metadata: {
        example_key: "Example subscription metadata"
    },
    methods_active: [
        "edit"
    ],
    methods_supported: [
        "edit"
    ],
    object: "subscription",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "Monthly",
    setup_amount: 10,
    status: "active",
    status_text: "Active",
    subscription_id: "sub-example-cxXtztIZhh",
    trial_end: 1712029748,
    trial_period_days: 14,
    trial_start: 0
}

List all

Get all subscriptions associated with the secret key provided in the request

Parameters

count optional
Default: 20
Number of subscriptions to return per request in the response. Must be between 1 and 500.
offset optional
Default: 0
Position to start returning subscriptions from. Used to paginate through all subscriptions. Must be between 0 and 10,000.
customer_id optional
Only return subscriptions matching this customer id.
created[max] optional
Maximum seconds since epoch (unix timestamp) that subscription must have been created before.
created[min] optional
Minimum seconds since epoch (unix timestamp) that subscription must have been created after.

Request

GET https://api.chargedesk.com/v1/subscriptions

Example Curl Command

curl https://api.chargedesk.com/v1/subscriptions?count=2 \
  -u YOUR_SECRET_KEY:

Example Response

{
    "count": 2,
    "offset": 0,
    "data": [
{
    amount: "34.00",
    amount_formatted: "2x $34.00 USD",
    amount_symbol: "$",
    billing_cycles_current: 1,
    billing_cycles_total: 0,
    canceled_at: 0,
    charges: 1,
    company: "company-example",
    currency: "USD",
    current_period_end: 1713449891,
    current_period_start: 1710820148,
    customer_id: "cus-example-QHW96q7CmS",
    ended_at: 0,
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    has_items: 0,
    interval: "month",
    interval_count: 1,
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/subscriptions/sub-example-cxXtztIZhh",
    metadata: {
        example_key: "Example subscription metadata"
    },
    methods_active: [
        "edit"
    ],
    methods_supported: [
        "edit"
    ],
    object: "subscription",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "Monthly",
    setup_amount: 10,
    status: "active",
    status_text: "Active",
    subscription_id: "sub-example-cxXtztIZhh",
    trial_end: 1712029748,
    trial_period_days: 14,
    trial_start: 0
},
... more data items here ...
    ]
}

Retrieve

Retrieves a subscription that has previously been created.

Request

GET https://api.chargedesk.com/v1/subscriptions/{SUBSCRIPTION_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/subscriptions/sub-example-cxXtztIZhh \
  -u YOUR_SECRET_KEY:

Example Response

{
    amount: "34.00",
    amount_formatted: "2x $34.00 USD",
    amount_symbol: "$",
    billing_cycles_current: 1,
    billing_cycles_total: 0,
    canceled_at: 0,
    charges: 1,
    company: "company-example",
    currency: "USD",
    current_period_end: 1713449891,
    current_period_start: 1710820148,
    customer_id: "cus-example-QHW96q7CmS",
    ended_at: 0,
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    has_items: 0,
    interval: "month",
    interval_count: 1,
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/subscriptions/sub-example-cxXtztIZhh",
    metadata: {
        example_key: "Example subscription metadata"
    },
    methods_active: [
        "edit"
    ],
    methods_supported: [
        "edit"
    ],
    object: "subscription",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "Monthly",
    setup_amount: 10,
    status: "active",
    status_text: "Active",
    subscription_id: "sub-example-cxXtztIZhh",
    trial_end: 1712029748,
    trial_period_days: 14,
    trial_start: 0
}

Update

Update the data stored for an existing subscription.

Parameters

subscription_id optional
Used to identify recurring charges. All charges for a subscription should share the same subscription id. Sent back in webhooks when subscriptions are modified.
customer_id optional
The ID of the customer that this subscription is associated with.
status optional
Default: active
The current status of this subscription. Possible values are 'requested', 'pending' (will transition to active), 'new' (awaiting payment method), 'trialing', 'active', 'past_due', 'canceled', 'unpaid', 'suspended' (can be reactivated at any time) or 'pending_cancel' (will be canceled at current period's end).
gateway_id optional
The id of gateway which this subscription occurred through. Will be set to the default gateway associated with your account if not provided. You can find the gateway id associated with a gateway on the setup page for your company.
Example: stripe
amount optional
The amount that this subscription is for. Must be a decimal value.
currency optional
The currency that this subscription uses.
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
setup_amount optional
Additional amount charged when subscription is first created. Must be a decimal value.
product_id optional
If defined, needs to match the ID of a product you have created or imported to ChargeDesk.
interval optional
How frequently the subscription is charged. Possible values are day, week, month or year.
Example: month
interval_count optional
How frequently the subscription is charged - combine with interval to define freqency. e.g. a fornightly subscription would have an interval of 'week' and an interval_count of '2'
Example: 6
quantity optional
The number of times this amount is applied. If provided, it must be a whole number great than 1.
Example: 2
current_period_start optional
When the current billing cycle started. In seconds since epoch (unix timestamp).
Example: 1710820148
current_period_end optional
When the current billing cycle will end. In seconds since epoch (unix timestamp).
Example: 1710820148
trial_start optional
When the trial period started (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1710820148
trial_end optional
When the trial period will end (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1710820148
ended_at optional
When the subscription ended (if not cancelled). In seconds since epoch (unix timestamp).
Example: 1710820148
canceled_at optional
When the subscription was cancelled. In seconds since epoch (unix timestamp).
Example: 1710820148
billing_cycles_total optional
Total number of billing cycles for this subscription.
Example: 10
billing_cycles_current optional
Current billing cycle for this subscription.
Example: 2
items[][id] optional
The ID of this subscription item.
items[][amount] optional
The amount of this subscription item.
items[][currency] optional
The currency of this subscription item.
items[][quantity] optional
The quantity of this subscription item.
items[][percent] optional
If the subscription item represents a discount, this defines the percentage discount.
items[][description] optional
The description of this subscription item.
metadata[key] optional
Set arbitrary metadata on this subscription.
Refer to: https://chargedesk.com/api-docs#information-metadata

Request

POST https://api.chargedesk.com/v1/subscriptions/{SUBSCRIPTION_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/subscriptions/sub-example-cxXtztIZhh \
  -u YOUR_SECRET_KEY: \
  -d "status=active"

Example Response

{
    amount: "34.00",
    amount_formatted: "2x $34.00 USD",
    amount_symbol: "$",
    billing_cycles_current: 1,
    billing_cycles_total: 0,
    canceled_at: 0,
    charges: 1,
    company: "company-example",
    currency: "USD",
    current_period_end: 1713449891,
    current_period_start: 1710820148,
    customer_id: "cus-example-QHW96q7CmS",
    ended_at: 0,
    first_seen: 1710820148,
    gateway_id: "",
    gateway_url: "",
    has_items: 0,
    interval: "month",
    interval_count: 1,
    items: [],
    logs: [],
    manage_url: "https://chargedesk.com/manage/company-example/subscriptions/sub-example-cxXtztIZhh",
    metadata: {
        example_key: "Example subscription metadata"
    },
    methods_active: [
        "edit"
    ],
    methods_supported: [
        "edit"
    ],
    object: "subscription",
    product_desc: "",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "Monthly",
    setup_amount: 10,
    status: "active",
    status_text: "Active",
    subscription_id: "sub-example-cxXtztIZhh",
    trial_end: 1712029748,
    trial_period_days: 14,
    trial_start: 0
}

Create

Creates a new product. Products are a general way of associating charges for the same type of sale together.

Parameters

product_id (required)
An identifier which ties all charges for the same product together. Used to provide additional information to the customer about what the charge was for.
duplicate optional
If an existing product with a matching product_id already exists, setting duplicate to 'update' allows the API request to not fail. Instead it will update the existing product with any new data.
Example: update
Refer to: https://chargedesk.com/api-docs#information-handling-duplicates
name optional
The name of the product as your customers will understand it.
description optional
A few sentences explaining what the product is. Must be 255 characters or less.
url optional
A url where more information can be found about this product, such as a product page on your website.
amount optional
A string representing the amount charged for this product. This amount must be in decimal format with period (.) separating the whole and fractional parts, for example USD is displayed in the usual '29.90' format where the amount is 29 dollars and 90 cents. In German, € 1 234,56 becomes '1234.56'
Do not include the currency symbol such as $ or €
Example: 34.00
currency optional
A 3 letter code representing the currency charged for this product. Refer to the link below for a list of supported currency codes.
Example: USD
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
quantity optional
The number of times this amount is applied. If provided, it must be a whole number great than 1.
Example: 2
gateway_id optional
The primary gateway associated with this product.
Example: stripe
chargeable optional
Default: true
Can new charges be created for this product? Will also generate a payment page if true.
interval optional
Choose how frequently the product is charged. Possible values are day, week, month, year or leave blank if the product is not a recurring charge.
interval_count optional
Default: 1
Multiplies the interval to provide a frequency for the product. e.g for every 6 months provide an interval_count of '6' an and interval of 'month'.
trial_period_days optional
The number of days which the trial period lasts if the product is a subscription. Enter 0 for none. Must be a positive integer.
billing_cycles_total optional
The maximum number of billing cycles if the product is a subscription. Enter 0 or leave blank for unlimited. Must be a positive integer. Not supported by all gateways.
setup_amount optional
An additional amount to charge when the product is initially created if the product is a subscription. Has the same requirements as the 'amount' field.

Request

POST https://api.chargedesk.com/v1/products

Example Curl Command

curl https://api.chargedesk.com/v1/products \
  -u YOUR_SECRET_KEY: \
  -d "product_id=prod-example-pKrNwQa7DF" \
  -d "name=Example Product" \
  -d "description=Example product description" \
  -d "amount=34.00" \
  -d "currency=USD"

Example Response

{
    amount: 34,
    amount_formatted: "$34.00 USD",
    amount_symbol: "$",
    billing_cycles_total: 0,
    chargeable: 1,
    charges: 1,
    company: "company-example",
    currency: "USD",
    description: "Example product description",
    first_seen: 1710820148,
    gateway_id: "",
    has_agent_log: 0,
    interval: "",
    interval_count: 1,
    logs: [],
    name: "Example Product",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "",
    setup_amount: 10,
    status: "complete",
    support_url: "https://chargedesk.com/company-example/product/prod-example-pKrNwQa7DF",
    taxable: 1,
    trial_period_days: 14,
    url: "https://example.com/product"
}

List all

Get all products associated with the secret key provided in the request

Parameters

count optional
Default: 20
Number of products to return per request in the response. Must be between 1 and 500.
offset optional
Default: 0
Position to start returning products from. Used to paginate through all products. Must be between 0 and 10,000.

Request

GET https://api.chargedesk.com/v1/products

Example Curl Command

curl https://api.chargedesk.com/v1/products?count=2 \
  -u YOUR_SECRET_KEY:

Example Response

{
    "count": 2,
    "offset": 0,
    "data": [
{
    amount: 34,
    amount_formatted: "$34.00 USD",
    amount_symbol: "$",
    billing_cycles_total: 0,
    chargeable: 1,
    charges: 1,
    company: "company-example",
    currency: "USD",
    description: "Example product description",
    first_seen: 1710820148,
    gateway_id: "",
    has_agent_log: 0,
    interval: "",
    interval_count: 1,
    logs: [],
    name: "Example Product",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "",
    setup_amount: 10,
    status: "complete",
    support_url: "https://chargedesk.com/company-example/product/prod-example-pKrNwQa7DF",
    taxable: 1,
    trial_period_days: 14,
    url: "https://example.com/product"
},
... more data items here ...
    ]
}

Retrieve

Retrieves a product that has previously been created.

Request

GET https://api.chargedesk.com/v1/products/{PRODUCT_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/products/prod-example-pKrNwQa7DF \
  -u YOUR_SECRET_KEY:

Example Response

{
    amount: 34,
    amount_formatted: "$34.00 USD",
    amount_symbol: "$",
    billing_cycles_total: 0,
    chargeable: 1,
    charges: 1,
    company: "company-example",
    currency: "USD",
    description: "Example product description",
    first_seen: 1710820148,
    gateway_id: "",
    has_agent_log: 0,
    interval: "",
    interval_count: 1,
    logs: [],
    name: "Example Product",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "",
    setup_amount: 10,
    status: "complete",
    support_url: "https://chargedesk.com/company-example/product/prod-example-pKrNwQa7DF",
    taxable: 1,
    trial_period_days: 14,
    url: "https://example.com/product"
}

Update

Update the data stored for an existing product.

Parameters

product_id optional
An identifier which ties all charges for the same product together. If a new value is provided here, this should then be used as the {PRODUCT_ID} for future requests.
name optional
The name of the product as your customers will understand it.
description optional
A few sentences explaining what the product is. Must be 255 characters or less.
url optional
A url where more information can be found about this product, such as a product page on your website.
amount optional
A string representing the amount charged for this product. This amount must be in decimal format with period (.) separating the whole and fractional parts, for example USD is displayed in the usual '29.90' format where the amount is 29 dollars and 90 cents. In German, € 1 234,56 becomes '1234.56'
Do not include the currency symbol such as $ or €
Example: 34.00
currency optional
A 3 letter code representing the currency charged for this product. Refer to the link below for a list of supported currency codes.
Example: USD
Refer to: https://chargedesk.com/api-docs#information-supported-currencies
quantity optional
The number of times this amount is applied. If provided, it must be a whole number great than 1.
Example: 2
gateway_id optional
The primary gateway associated with this product.
Example: stripe
chargeable optional
Default: true
Can new charges be created for this product? Will also generate a payment page if true.
interval optional
Choose how frequently the product is charged. Possible values are day, week, month, year or leave blank if the product is not a recurring charge.
interval_count optional
Default: 1
Multiplies the interval to provide a frequency for the product. e.g for every 6 months provide an interval_count of '6' an and interval of 'month'.
trial_period_days optional
The number of days which the trial period lasts if the product is a subscription. Enter 0 for none. Must be a positive integer.
billing_cycles_total optional
The maximum number of billing cycles if the product is a subscription. Enter 0 or leave blank for unlimited. Must be a positive integer. Not supported by all gateways.
setup_amount optional
An additional amount to charge when the product is initially created if the product is a subscription. Has the same requirements as the 'amount' field.

Request

POST https://api.chargedesk.com/v1/products/{PRODUCT_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/products/prod-example-pKrNwQa7DF \
  -u YOUR_SECRET_KEY: \
  -d "name=Example Product"

Example Response

{
    amount: 34,
    amount_formatted: "$34.00 USD",
    amount_symbol: "$",
    billing_cycles_total: 0,
    chargeable: 1,
    charges: 1,
    company: "company-example",
    currency: "USD",
    description: "Example product description",
    first_seen: 1710820148,
    gateway_id: "",
    has_agent_log: 0,
    interval: "",
    interval_count: 1,
    logs: [],
    name: "Example Product",
    product_id: "prod-example-pKrNwQa7DF",
    quantity: 2,
    readable_interval: "",
    setup_amount: 10,
    status: "complete",
    support_url: "https://chargedesk.com/company-example/product/prod-example-pKrNwQa7DF",
    taxable: 1,
    trial_period_days: 14,
    url: "https://example.com/product"
}

Create

Creates a new webhooks.

Parameters

url (required)
A valid URL endpoint for the webhook to send notifications to.
all optional
Specify that this webhook should receive all possible notifications.
notifications optional
A list of notifications for this webhook to send requests for. A list of all possible notifications can be found below.

Request

POST https://api.chargedesk.com/v1/webhooks

Example Curl Command

curl https://api.chargedesk.com/v1/webhooks \
  -u YOUR_SECRET_KEY: \
  -d "url=https://yoursite.com/chargedesk-webhook" \
  -d "all=1"

Example Response

{
    "webhook_id": "{WEBHOOK_ID}"
}

Notifications

Get a list of all possible notifications.

 

Request

GET https://api.chargedesk.com/v1/webhooks/notifications

Example Curl Command

curl https://api.chargedesk.com/v1/webhooks/notifications \
  -u YOUR_SECRET_KEY:

Example Response

[
    {
        notification: "charge_new",
        object: "Charge",
        name: "Charge Created",
        description: "Sent when a new charge is created."
    },
    {
        notification: "charge_updated",
        object: "Charge",
        name: "Charge Updated",
        description: "Sent when a charge is updated."
    },
    {
        notification: "charge_request",
        object: "Charge",
        name: "Charge Requested",
        description: "Sent when a payment request is created."
    },
    {
        notification: "charge_paid",
        object: "Charge",
        name: "Charge Paid",
        description: "Sent when a charge is successfully paid. Does not include payment requests."
    },
    {
        notification: "charge_request_paid",
        object: "Charge",
        name: "Charge Request Paid",
        description: "Sent when a payment request is successfully paid by a customer."
    },
    {
        notification: "charge_pending_paid",
        object: "Charge",
        name: "Charge Pending Paid",
        description: "Sent when a previously pending payment is successfully paid."
    },
    {
        notification: "charge_refunded",
        object: "Charge",
        name: "Charge Refunded",
        description: "Sent when a charge is refunded."
    },
    {
        notification: "charge_failed",
        object: "Charge",
        name: "Charge Failed",
        description: "Sent when a charge fails, often due to an issue with the customer's card."
    },
    {
        notification: "charge_disputed",
        object: "Charge",
        name: "Charge Disputed",
        description: "Sent when a charge is disputed, often due to a chargeback by the customer."
    },
    {
        notification: "charge_request_reminder",
        object: "Charge",
        name: "Charge Unpaid Payment Request",
        description: "Sent when a payment request hasn't been paid for X days."
    },
    {
        notification: "customer_new",
        object: "Customer",
        name: "Customer Created",
        description: "Sent when a new customer is created."
    },
    {
        notification: "customer_updated",
        object: "Customer",
        name: "Customer Updated",
        description: "Sent when a customer is updated."
    },
    {
        notification: "customer_first_paid",
        object: "Customer",
        name: "Customer First Payment",
        description: "Sent when a customer makes their first successful payment."
    },
    {
        notification: "customer_delinquent",
        object: "Customer",
        name: "Customer Delinquent",
        description: "Sent when a customer is marked as delinquent."
    },
    {
        notification: "subscription_new",
        object: "Subscription",
        name: "Subscription Created",
        description: "Sent when a new subscription is created."
    },
    {
        notification: "subscription_updated",
        object: "Subscription",
        name: "Subscription Updated",
        description: "Sent when a subscription is updated."
    },
    {
        notification: "subscription_upgraded",
        object: "Subscription",
        name: "Subscription Upgraded",
        description: "Sent when a subscription is upgraded."
    },
    {
        notification: "subscription_downgraded",
        object: "Subscription",
        name: "Subscription Downgraded",
        description: "Sent when a subscription is downgraded."
    },
    {
        notification: "subscription_past_due",
        object: "Subscription",
        name: "Subscription Past Due",
        description: "Sent when a subscription goes past due."
    },
    {
        notification: "subscription_canceled",
        object: "Subscription",
        name: "Subscription Canceled",
        description: "Sent when a subscription is canceled or unpaid."
    },
    {
        notification: "subscription_suspended",
        object: "Subscription",
        name: "Subscription Suspended",
        description: "Sent when a subscription is suspended or paused."
    },
    {
        notification: "subscription_reactivated",
        object: "Subscription",
        name: "Subscription Reactivated",
        description: "Sent when a subscription is reactivated."
    },
    {
        notification: "subscription_upcoming_payment",
        object: "Subscription",
        name: "Subscription Upcoming Payment on Active Subscription",
        description: "Sent when a charge on an active subscription is due in X days."
    },
    {
        notification: "subscription_trial_ending",
        object: "Subscription",
        name: "Subscription Subscription Trial Ends Soon",
        description: "Sent when a charge on a trial subscription is due in X days."
    },
    {
        notification: "agent_log_new",
        object: "AgentLog",
        name: "Agent Log Created",
        description: "Sent when a new agent log is created."
    }
]

Delete

Delete an existing webhook.

Request

DELETE https://api.chargedesk.com/v1/webhooks/{WEBHOOK_ID}

Example Curl Command

curl https://api.chargedesk.com/v1/webhooks/{WEBHOOK_ID} \
  -u YOUR_SECRET_KEY: \
  -X DELETE

Create

Creates a new ChargeDesk agent. An email will be sent to the agent inviting them to create a password and setup their ChargeDesk account. If agent already exists their role will be updated.

Parameters

name (required)
Agent name.
email (required)
Agent email address.
role (required)
Role for agent. Can be `read-only`, `agent` or `admin`. Custom roles are also supported using the role name.

Request

POST https://api.chargedesk.com/v1/agents

Example Curl Command

curl https://api.chargedesk.com/v1/agents \
  -u YOUR_SECRET_KEY: \
  -d "name=John Example" \
  -d "email=john@example.com" \
  -d "role=agent"

Delete

Delete an existing ChargeDesk agent with an given email address.

Request

DELETE https://api.chargedesk.com/v1/agents/{AGENT_EMAIL}

Example Curl Command

curl https://api.chargedesk.com/v1/agents/{AGENT_EMAIL} \
  -u YOUR_SECRET_KEY: \
  -X DELETE

Agent Activity

Get all products associated with the secret key provided in the request

Parameters

count optional
Default: 20
Number of logs to return per request in the response. Must be between 1 and 500.
offset optional
Default: 0
Position to start returning logs from. Used to paginate through all logs. Must be between 0 and 10,000.
object_id optional
Only return logs matching a specific object id. Required when object_id is set. Must be the ID matching the object being queried. For example, a charge ID or customer ID.
object_type optional
Only return logs matching a specific object type. Must be 'charge', 'customer', 'subscription' or 'product'.
Example: charge
action_type optional
Only return logs matching a specific action. Requires object_type to also be set.
Example: refund
occurred[max] optional
Maximum seconds since epoch (unix timestamp) that logs must have occurred before.
occurred[min] optional
Minimum seconds since epoch (unix timestamp) that logs must have occurred after.

Request

GET https://api.chargedesk.com/v1/log/activity

Example Curl Command

curl https://api.chargedesk.com/v1/log/activity?count=2 \
  -u YOUR_SECRET_KEY:

Example Response

{
    "count": 2,
    "offset": 0,
    "data": [
{
    action_params: false,
    action_reason: "Example refund",
    action_type: "refund",
    company: "company-example",
    context: null,
    description: "Charge Refunded",
    event: "charge-refund",
    ip: "1.2.3.4",
    object_id: "example-8p1KDdjbM0EGhRFncTstwYBB",
    object_type: "charge",
    occurred: 1710820148,
    params: null,
    source: "web",
    sub_description: ""
},
... more data items here ...
    ]
}

Subscription Cancellations

Get a list of customer initiated cancellations and their reasons.

Parameters

count optional
Default: 20
Number of logs to return per request in the response. Must be between 1 and 500.
offset optional
Default: 0
Position to start returning logs from. Used to paginate through all logs. Must be between 0 and 10,000.
action optional
Only return logs matching a specific action. Must be 'support' (cancellation request was sent to support, not automatically actioned), 'cancel', 'pause' or 'reactivate'.
occurred[max] optional
Maximum seconds since epoch (unix timestamp) that cancellation must have occurred before.
occurred[min] optional
Minimum seconds since epoch (unix timestamp) that cancellation must have occurred after.

Request

GET https://api.chargedesk.com/v1/log/cancellations

Example Curl Command

curl https://api.chargedesk.com/v1/log/cancellations?count=2 \
  -u YOUR_SECRET_KEY:

Example Response

{
    "count": 2,
    "offset": 0,
    "data": [
{
    action: "cancel",
    customer_id: "cus-example-QHW96q7CmS",
    email: "customer@example.com",
    ip: "1.2.3.4",
    method: "at_period_end",
    occurred: 1710820148,
    reason: "Example cancellation for demonstration purposes",
    subscription_id: "sub-example-cxXtztIZhh"
},
... more data items here ...
    ]
}

API Authentication

The ChargeDesk API is authenticated using HTTP Basic Authentication. Pass your secret key in the basic auth username. A password is not required.

Each company you create on ChargeDesk has their own secret key and must have API access enabled. You can turn on API access for your company and find your secret key at https://chargedesk.com/connect/api

Every piece of example code on the page contains all the authentication information you need. If you login with your account and visit this page, your secret key from the last company you looked at will be filled out for you (if the API is active for that company).

Request

GET https://api.chargedesk.com/v1/charges

Example Curl Command

curl https://api.chargedesk.com/v1/charges?count=2 \
  -u YOUR_SECRET_KEY:

Rate Limiting

Please limit your API requests to 60 requests per minute. If you make more requests than this, you will be blocked from making another request for 60 seconds.

When your API requests are rate limited, you will receive a 429 response code with a 'Retry-After: X' header to let you know how long until you can try your request again.

Metadata

Arbitrary metadata can be assigned to charges, customers and subscriptions. The metadata is then visible to support agents and returned in future API calls and webhooks.

Metadata should be provided in key, value pairs. Keys may be up to 32 characters, and values up to 255 characters.

Handling Duplicates

Charges, Customers, Subscriptions and Products all have unique IDs (transaction_id for Charges, customer_id for Customers, subscription_id for Subscriptions and product_id for Products). When importing data from your system, you may not always know if the relevant resource has already been imported into ChargeDesk.

When this is the case, to save duplicating API calls, you can set duplicate=update on any of the creation endpoints for these resources. If existing data matching the unique ID for the resource already exists, the request will not fail and instead will update the relevant resource with the latest data.

Supported Currencies

Below is a list of all currency codes supported by ChargeDesk.

Please note that in order to create a charge in a currency, it must be supported by your connected payment gateways.

AED
United Arab Emirates Dirham

AFN
Afghan Afghani

ALL
Albanian Lek

AMD
Armenian Dram

ANG
Netherlands Antillean Guilder

AOA
Angolan Kwanza

ARS
Argentine Peso

AUD
Australian Dollar

AWG
Aruban Florin

AZN
Azerbaijani Manat

BAM
Bosnia-Herzegovina Convertible Mark

BBD
Barbadian Dollar

BDT
Bangladeshi Taka

BGN
Bulgarian Lev

BHD
Bahraini Dinar

BIF
Burundian Franc

BMD
Bermudan Dollar

BND
Brunei Dollar

BOB
Bolivian Boliviano

BRL
Brazilian Real

BSD
Bahamian Dollar

BTC
Bitcoin

BTN
Bhutanese Ngultrum

BWP
Botswanan Pula

BYN
Belarusian Ruble

BZD
Belize Dollar

CAD
Canadian Dollar

CDF
Congolese Franc

CHF
Swiss Franc

CLF
Chilean Unit of Account (UF)

CLP
Chilean Peso

CNH
Chinese Yuan (Offshore)

CNY
Chinese Yuan

COP
Colombian Peso

CRC
Costa Rican Colón

CUC
Cuban Convertible Peso

CUP
Cuban Peso

CVE
Cape Verdean Escudo

CZK
Czech Republic Koruna

DJF
Djiboutian Franc

DKK
Danish Krone

DOP
Dominican Peso

DZD
Algerian Dinar

EGP
Egyptian Pound

ERN
Eritrean Nakfa

ETB
Ethiopian Birr

EUR
Euro

FJD
Fijian Dollar

FKP
Falkland Islands Pound

GBP
British Pound Sterling

GEL
Georgian Lari

GGP
Guernsey Pound

GHS
Ghanaian Cedi

GIP
Gibraltar Pound

GMD
Gambian Dalasi

GNF
Guinean Franc

GTQ
Guatemalan Quetzal

GYD
Guyanaese Dollar

HKD
Hong Kong Dollar

HNL
Honduran Lempira

HRK
Croatian Kuna

HTG
Haitian Gourde

HUF
Hungarian Forint

IDR
Indonesian Rupiah

ILS
Israeli New Sheqel

IMP
Manx pound

INR
Indian Rupee

IQD
Iraqi Dinar

IRR
Iranian Rial

ISK
Icelandic Króna

JEP
Jersey Pound

JMD
Jamaican Dollar

JOD
Jordanian Dinar

JPY
Japanese Yen

KES
Kenyan Shilling

KGS
Kyrgystani Som

KHR
Cambodian Riel

KMF
Comorian Franc

KPW
North Korean Won

KRW
South Korean Won

KWD
Kuwaiti Dinar

KYD
Cayman Islands Dollar

KZT
Kazakhstani Tenge

LAK
Laotian Kip

LBP
Lebanese Pound

LKR
Sri Lankan Rupee

LRD
Liberian Dollar

LSL
Lesotho Loti

LYD
Libyan Dinar

MAD
Moroccan Dirham

MDL
Moldovan Leu

MGA
Malagasy Ariary

MKD
Macedonian Denar

MMK
Myanma Kyat

MNT
Mongolian Tugrik

MOP
Macanese Pataca

MRU
Mauritanian Ouguiya

MUR
Mauritian Rupee

MVR
Maldivian Rufiyaa

MWK
Malawian Kwacha

MXN
Mexican Peso

MYR
Malaysian Ringgit

MZN
Mozambican Metical

NAD
Namibian Dollar

NGN
Nigerian Naira

NIO
Nicaraguan Córdoba

NOK
Norwegian Krone

NPR
Nepalese Rupee

NZD
New Zealand Dollar

OMR
Omani Rial

PAB
Panamanian Balboa

PEN
Peruvian Nuevo Sol

PGK
Papua New Guinean Kina

PHP
Philippine Peso

PKR
Pakistani Rupee

PLN
Polish Zloty

PYG
Paraguayan Guarani

QAR
Qatari Rial

RON
Romanian Leu

RSD
Serbian Dinar

RUB
Russian Ruble

RWF
Rwandan Franc

SAR
Saudi Riyal

SBD
Solomon Islands Dollar

SCR
Seychellois Rupee

SDG
Sudanese Pound

SEK
Swedish Krona

SGD
Singapore Dollar

SHP
Saint Helena Pound

SLL
Sierra Leonean Leone

SOS
Somali Shilling

SRD
Surinamese Dollar

SSP
South Sudanese Pound

STD
São Tomé and Príncipe Dobra (pre-2018)

STN
São Tomé and Príncipe Dobra

SVC
Salvadoran Colón

SYP
Syrian Pound

SZL
Swazi Lilangeni

THB
Thai Baht

TJS
Tajikistani Somoni

TMT
Turkmenistani Manat

TND
Tunisian Dinar

TOP
Tongan Pa'anga

TRY
Turkish Lira

TTD
Trinidad and Tobago Dollar

TWD
New Taiwan Dollar

TZS
Tanzanian Shilling

UAH
Ukrainian Hryvnia

UGX
Ugandan Shilling

USD
United States Dollar

UYU
Uruguayan Peso

UZS
Uzbekistan Som

VES
Venezuelan Bolívar Soberano

VND
Vietnamese Dong

VUV
Vanuatu Vatu

WST
Samoan Tala

XAF
CFA Franc BEAC

XAG
Silver Ounce

XAU
Gold Ounce

XCD
East Caribbean Dollar

XDR
Special Drawing Rights

XOF
CFA Franc BCEAO

XPD
Palladium Ounce

XPF
CFP Franc

XPT
Platinum Ounce

YER
Yemeni Rial

ZAR
South African Rand

ZMW
Zambian Kwacha

ZWL
Zimbabwean Dollar