Add to Chrome
x
Add to Chrome
Create ChargeCreates 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. Parametersusing (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 |
RequestPOST https://api.chargedesk.com/v1/gateway/products/charge Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$response = ChargeDesk_Gateway_Product::charge(array(
"using" => "card",
"customer" => array(
"id" => "cus-example-WgwN7cPipB",
)
"amount" => "34.00",
"currency" => "USD",
));
// $response->charge now contains the created Charge
echo $response->charge->support_url; // print the support url for this charge
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}}
|
|
Create SubscriptionCreate 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. Parametersusing (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.
|
RequestPOST https://api.chargedesk.com/v1/gateway/products/charge Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$response = ChargeDesk_Gateway_Product::charge(array(
"using" => "card",
"customer" => array(
"id" => "cus-example-WgwN7cPipB",
)
"amount" => "34.00",
"currency" => "USD",
"product" => array(
"interval" => "month",
"trial_period_days" => "14",
)
));
echo $response->subscription; // print the details of the created subscription
echo $response->charge; // print the details of the initial charge for the subscription (if any)
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: 1734872712,
current_period_start: 1732242969,
customer_id: "cus-example-WgwN7cPipB",
ended_at: 0,
first_seen: 1732242969,
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-KbEZslj29A",
metadata: {
example_key: "Example subscription metadata"
},
methods_active: [
"edit"
],
methods_supported: [
"edit"
],
object: "subscription",
product_desc: "",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "Monthly",
setup_amount: 10,
status: "active",
status_text: "Active",
subscription_id: "sub-example-KbEZslj29A",
trial_end: 1733452569,
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}}
|
|
Request PaymentRequest 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. Parametersusing 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.
|
RequestPOST https://api.chargedesk.com/v1/gateway/products/charge Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$request = ChargeDesk_Gateway_Product::charge(array(
"contact" => "jane@example.com",
"amount" => "34.00",
"currency" => "USD",
));
// $request now contains details of the payment request
echo $request->charge; // print the details of the created charge
echo $request->subscription; // print the details of the created subscription
echo $request->pay_link; // print the payment url for this request (if no email or phone number was set)
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}}
|
|
Refund ChargeProcess 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. Parametersamount 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
|
RequestPOST https://api.chargedesk.com/v1/gateway/charges/{CHARGE_ID}/refund
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charge = ChargeDesk_Gateway_Charge::refund("{CHARGE_ID}");
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "partially refunded",
status_text: "partially refunded",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}
|
|
Capture ChargeCapture 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. Parametersamount 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 |
RequestPOST https://api.chargedesk.com/v1/gateway/charges/{CHARGE_ID}/capture
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charge = ChargeDesk_Gateway_Charge::capture("{CHARGE_ID}");
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}
|
|
Cancel SubscriptionCancels 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. Parameterslog_reason optional
Provide a reason to be logged in the activity log this refund
|
RequestPOST https://api.chargedesk.com/v1/gateway/subscriptions/{SUBSCRIPTION_ID}/cancel
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$subscription = ChargeDesk_Gateway_Subscription::cancel("{SUBSCRIPTION_ID}");
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: 1734872712,
current_period_start: 1732242969,
customer_id: "cus-example-WgwN7cPipB",
ended_at: 0,
first_seen: 1732242969,
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-KbEZslj29A",
metadata: {
example_key: "Example subscription metadata"
},
methods_active: [],
methods_supported: [
"edit"
],
object: "subscription",
product_desc: "",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "Monthly",
setup_amount: 10,
status: "canceled",
status_text: "Canceled",
subscription_id: "sub-example-KbEZslj29A",
trial_end: 1733452569,
trial_period_days: 14,
trial_start: 0
}
|
|
Edit Subscription PlansEdits 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. Parametersplans[][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: 1732242969 period_end optional
Unix timestamp for when the subscription's current period ends. Recurly only.
Example: 1732242969 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 |
RequestPOST https://api.chargedesk.com/v1/gateway/subscriptions/{SUBSCRIPTION_ID}/plans
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: 1734872712,
current_period_start: 1732242969,
customer_id: "cus-example-WgwN7cPipB",
ended_at: 0,
first_seen: 1732242969,
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-KbEZslj29A",
metadata: {
example_key: "Example subscription metadata"
},
methods_active: [
"edit"
],
methods_supported: [
"edit"
],
object: "subscription",
product_desc: "",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "Monthly",
setup_amount: 10,
status: "active",
status_text: "Active",
subscription_id: "sub-example-KbEZslj29A",
trial_end: 1733452569,
trial_period_days: 14,
trial_start: 0
}
|
|
Cancel Payment RequestCancel 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. |
RequestPOST https://api.chargedesk.com/v1/gateway/charges/{CHARGE_ID}/void
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charge = ChargeDesk_Gateway_Charge::void("{CHARGE_ID}");
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}
|
|
CreateCreates 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.Parametersamount (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', 'draft' or 'unclaimed'. 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 |
RequestPOST https://api.chargedesk.com/v1/charges Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charge = ChargeDesk_Charge::create(array(
"amount" => "34.00",
"currency" => "USD",
"customer" => array(
"id" => "cus-example-WgwN7cPipB",
)
));
// $charge now contains the created Charge
echo $charge->support_url; // print the support url for this charge
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}
|
|
List allGet all charges associated with the secret key provided in the requestParameterscount 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', 'draft' or 'unclaimed'
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.
|
RequestGET https://api.chargedesk.com/v1/charges Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charges = ChargeDesk_Charge::find(array(
"count" => "2",
));
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
},
... more data items here ...
]
}
|
|
RetrieveRetrieves a charge that has previously been created. |
RequestGET https://api.chargedesk.com/v1/charges/{CHARGE_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charge = ChargeDesk_Charge::retrieve("{CHARGE_ID}");
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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}
|
|
UpdateUpdates an existing charge with new information.Parametersamount 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', 'draft' or 'unclaimed'. 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 |
RequestPOST https://api.chargedesk.com/v1/charges/{CHARGE_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charge = ChargeDesk_Charge::update("{CHARGE_ID}", array(
"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-89BQ7oI7Dgq8RVj4UztaQB0i",
company: "company-example",
currency: "USD",
customer_country: "US",
customer_email: "jane@example.com",
customer_id: "cus-example-WgwN7cPipB",
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-89BQ7oI7Dgq8RVj4UztaQB0i/invoice/download",
invoice_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i/invoice",
is_paid: true,
last_4_digits: "1234",
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/charges/example-89BQ7oI7Dgq8RVj4UztaQB0i",
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: 1732242969,
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-c195mrw8wK",
refunded_at_formatted: "",
sent_invoice: "",
sent_invoice_reminder: "",
status: "paid",
status_text: "paid",
subscription_id: "sub-example-KbEZslj29A",
support_email: "company-example+example-89BQ7oI7Dgq8RVj4UztaQB0i@chargedesk.com",
support_url: "https://chargedesk.com/company-example/example-89BQ7oI7Dgq8RVj4UztaQB0i",
transaction_id: "transaction-example-oR5Ja3xVpB"
}
|
|
Email ChargeSend 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.Parametersemail optional
The email address to send the notification to.
Example: example@customer.com |
RequestPOST https://api.chargedesk.com/v1/charges/{CHARGE_ID}/email
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charge = ChargeDesk_Gateway_Charge::email("{CHARGE_ID}");
|
|
Preview ChargePreview 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.Parameterscharge_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.
|
RequestGET https://api.chargedesk.com/v1/charges/preview Example Response{
"subtotalAmount": 10,
"subtotalAmountFormatted": "$10.00",
"taxRates": [
{
"name": "Tax",
"rate": 10,
"amount": 1,
"amountFormatted": "$1.00"
}
],
"totalAmount": 11,
"totalAmountFormatted": "$11.00"
}
|
|
DeleteDeletes a charge record. |
RequestDELETE https://api.chargedesk.com/v1/charges/{CHARGE_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$result = ChargeDesk_Charge::delete("{CHARGE_ID}");
|
|
CreateUsed to tie all charges from the same person together.Parameterscustomer_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 |
RequestPOST https://api.chargedesk.com/v1/customers Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$customer = ChargeDesk_Customer::create(array(
"customer_id" => "cus-example-WgwN7cPipB",
"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-WgwN7cPipB",
delinquent: 0,
description: "An example customer",
edited: 0,
email: "jane@example.com",
first_name: "Jane",
first_seen: 1732242969,
gateway_id: "",
gateway_url: "",
invoice_details: "",
items: [],
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-WgwN7cPipB",
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 allGet all customers associated with the secret key provided in the requestParameterscount 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.
|
RequestGET https://api.chargedesk.com/v1/customers Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$customers = ChargeDesk_Customer::find(array(
"count" => "2",
));
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-WgwN7cPipB",
delinquent: 0,
description: "An example customer",
edited: 0,
email: "jane@example.com",
first_name: "Jane",
first_seen: 1732242969,
gateway_id: "",
gateway_url: "",
invoice_details: "",
items: [],
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-WgwN7cPipB",
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 ...
]
}
|
|
RetrieveRetrieves a customer that has previously been created. |
RequestGET https://api.chargedesk.com/v1/customers/{CUSTOMER_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$customer = ChargeDesk_Customer::retrieve("{CUSTOMER_ID}");
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-WgwN7cPipB",
delinquent: 0,
description: "An example customer",
edited: 0,
email: "jane@example.com",
first_name: "Jane",
first_seen: 1732242969,
gateway_id: "",
gateway_url: "",
invoice_details: "",
items: [],
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-WgwN7cPipB",
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"
}
|
|
UpdateUpdate the data stored for an existing customer.Parameterscustomer_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 |
RequestPOST https://api.chargedesk.com/v1/customers/{CUSTOMER_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$customer = ChargeDesk_Customer::update("{CUSTOMER_ID}", array(
"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-WgwN7cPipB",
delinquent: 0,
description: "An example customer",
edited: 0,
email: "jane@example.com",
first_name: "Jane",
first_seen: 1732242969,
gateway_id: "",
gateway_url: "",
invoice_details: "",
items: [],
logs: [],
manage_url: "https://chargedesk.com/manage/company-example/customers/cus-example-WgwN7cPipB",
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"
}
|
|
GroupedGets 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.Parameterscustomer[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.
|
RequestGET https://api.chargedesk.com/v1/customers/grouped Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$grouped = ChargeDesk_Customer::grouped(array(
"customer[email]" => "james@example.com",
));
|
|
DeleteDeletes a customer record.Parametersdelete_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. |
RequestDELETE https://api.chargedesk.com/v1/customers/{CUSTOMER_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$result = ChargeDesk_Customer::delete("{CUSTOMER_ID}");
|
|
CreateCreates 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.Parameterssubscription_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: 1732242969 current_period_end optional
When the current billing cycle will end. In seconds since epoch (unix timestamp).
Example: 1732242969 trial_start optional
When the trial period started (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1732242969 trial_end optional
When the trial period will end (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1732242969 ended_at optional
When the subscription ended (if not cancelled). In seconds since epoch (unix timestamp).
Example: 1732242969 canceled_at optional
When the subscription was cancelled. In seconds since epoch (unix timestamp).
Example: 1732242969 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 |
RequestPOST https://api.chargedesk.com/v1/subscriptions Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$subscription = ChargeDesk_Subscription::create(array(
"subscription_id" => "sub-example-KbEZslj29A",
"customer_id" => "cus-example-WgwN7cPipB",
"amount" => "34.00",
"currency" => "USD",
"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: 1734872712,
current_period_start: 1732242969,
customer_id: "cus-example-WgwN7cPipB",
ended_at: 0,
first_seen: 1732242969,
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-KbEZslj29A",
metadata: {
example_key: "Example subscription metadata"
},
methods_active: [
"edit"
],
methods_supported: [
"edit"
],
object: "subscription",
product_desc: "",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "Monthly",
setup_amount: 10,
status: "active",
status_text: "Active",
subscription_id: "sub-example-KbEZslj29A",
trial_end: 1733452569,
trial_period_days: 14,
trial_start: 0
}
|
|
List allGet all subscriptions associated with the secret key provided in the requestParameterscount 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.
|
RequestGET https://api.chargedesk.com/v1/subscriptions Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$subscriptions = ChargeDesk_Subscription::find(array(
"count" => "2",
));
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: 1734872712,
current_period_start: 1732242969,
customer_id: "cus-example-WgwN7cPipB",
ended_at: 0,
first_seen: 1732242969,
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-KbEZslj29A",
metadata: {
example_key: "Example subscription metadata"
},
methods_active: [
"edit"
],
methods_supported: [
"edit"
],
object: "subscription",
product_desc: "",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "Monthly",
setup_amount: 10,
status: "active",
status_text: "Active",
subscription_id: "sub-example-KbEZslj29A",
trial_end: 1733452569,
trial_period_days: 14,
trial_start: 0
},
... more data items here ...
]
}
|
|
RetrieveRetrieves a subscription that has previously been created. |
RequestGET https://api.chargedesk.com/v1/subscriptions/{SUBSCRIPTION_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$subscription = ChargeDesk_Subscription::retrieve("{SUBSCRIPTION_ID}");
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: 1734872712,
current_period_start: 1732242969,
customer_id: "cus-example-WgwN7cPipB",
ended_at: 0,
first_seen: 1732242969,
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-KbEZslj29A",
metadata: {
example_key: "Example subscription metadata"
},
methods_active: [
"edit"
],
methods_supported: [
"edit"
],
object: "subscription",
product_desc: "",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "Monthly",
setup_amount: 10,
status: "active",
status_text: "Active",
subscription_id: "sub-example-KbEZslj29A",
trial_end: 1733452569,
trial_period_days: 14,
trial_start: 0
}
|
|
UpdateUpdate the data stored for an existing subscription.Parameterssubscription_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: 1732242969 current_period_end optional
When the current billing cycle will end. In seconds since epoch (unix timestamp).
Example: 1732242969 trial_start optional
When the trial period started (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1732242969 trial_end optional
When the trial period will end (if status is trailing). In seconds since epoch (unix timestamp).
Example: 1732242969 ended_at optional
When the subscription ended (if not cancelled). In seconds since epoch (unix timestamp).
Example: 1732242969 canceled_at optional
When the subscription was cancelled. In seconds since epoch (unix timestamp).
Example: 1732242969 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 |
RequestPOST https://api.chargedesk.com/v1/subscriptions/{SUBSCRIPTION_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$subscription = ChargeDesk_Subscription::update("{SUBSCRIPTION_ID}", array(
"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: 1734872712,
current_period_start: 1732242969,
customer_id: "cus-example-WgwN7cPipB",
ended_at: 0,
first_seen: 1732242969,
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-KbEZslj29A",
metadata: {
example_key: "Example subscription metadata"
},
methods_active: [
"edit"
],
methods_supported: [
"edit"
],
object: "subscription",
product_desc: "",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "Monthly",
setup_amount: 10,
status: "active",
status_text: "Active",
subscription_id: "sub-example-KbEZslj29A",
trial_end: 1733452569,
trial_period_days: 14,
trial_start: 0
}
|
|
CreateCreates a new product. Products are a general way of associating charges for the same type of sale together.Parametersproduct_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.
|
RequestPOST https://api.chargedesk.com/v1/products Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$product = ChargeDesk_Product::create(array(
"product_id" => "prod-example-c195mrw8wK",
"name" => "Example Product",
"description" => "Example product description",
"amount" => "34.00",
"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: 1732242969,
gateway_id: "",
has_agent_log: 0,
interval: "",
interval_count: 1,
logs: [],
name: "Example Product",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "",
setup_amount: 10,
status: "complete",
support_url: "https://chargedesk.com/company-example/product/prod-example-c195mrw8wK",
taxable: 1,
trial_period_days: 14,
url: "https://example.com/product"
}
|
|
List allGet all products associated with the secret key provided in the requestParameterscount 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. |
RequestGET https://api.chargedesk.com/v1/products Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$products = ChargeDesk_Product::find(array(
"count" => "2",
));
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: 1732242969,
gateway_id: "",
has_agent_log: 0,
interval: "",
interval_count: 1,
logs: [],
name: "Example Product",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "",
setup_amount: 10,
status: "complete",
support_url: "https://chargedesk.com/company-example/product/prod-example-c195mrw8wK",
taxable: 1,
trial_period_days: 14,
url: "https://example.com/product"
},
... more data items here ...
]
}
|
|
RetrieveRetrieves a product that has previously been created. |
RequestGET https://api.chargedesk.com/v1/products/{PRODUCT_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$product = ChargeDesk_Product::retrieve("{PRODUCT_ID}");
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: 1732242969,
gateway_id: "",
has_agent_log: 0,
interval: "",
interval_count: 1,
logs: [],
name: "Example Product",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "",
setup_amount: 10,
status: "complete",
support_url: "https://chargedesk.com/company-example/product/prod-example-c195mrw8wK",
taxable: 1,
trial_period_days: 14,
url: "https://example.com/product"
}
|
|
UpdateUpdate the data stored for an existing product.Parametersproduct_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.
|
RequestPOST https://api.chargedesk.com/v1/products/{PRODUCT_ID}
Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$product = ChargeDesk_Product::update("{PRODUCT_ID}", array(
"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: 1732242969,
gateway_id: "",
has_agent_log: 0,
interval: "",
interval_count: 1,
logs: [],
name: "Example Product",
product_id: "prod-example-c195mrw8wK",
quantity: 2,
readable_interval: "",
setup_amount: 10,
status: "complete",
support_url: "https://chargedesk.com/company-example/product/prod-example-c195mrw8wK",
taxable: 1,
trial_period_days: 14,
url: "https://example.com/product"
}
|
|
CreateCreates a new webhooks.Parametersurl (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.
|
RequestPOST https://api.chargedesk.com/v1/webhooks Example Response{
"webhook_id": "{WEBHOOK_ID}"
}
|
|
NotificationsGet a list of all possible notifications. |
RequestGET https://api.chargedesk.com/v1/webhooks/notifications 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."
}
]
|
|
DeleteDelete an existing webhook. |
RequestDELETE https://api.chargedesk.com/v1/webhooks/{WEBHOOK_ID}
|
|
CreateCreates 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.Parametersname (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.
|
RequestPOST https://api.chargedesk.com/v1/agents |
|
DeleteDelete an existing ChargeDesk agent with an given email address. |
RequestDELETE https://api.chargedesk.com/v1/agents/{AGENT_EMAIL}
|
|
Agent ActivityGet all products associated with the secret key provided in the requestParameterscount 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.
|
RequestGET https://api.chargedesk.com/v1/log/activity 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-89BQ7oI7Dgq8RVj4UztaQB0i",
object_type: "charge",
occurred: 1732242969,
params: null,
source: "web",
sub_description: ""
},
... more data items here ...
]
}
|
|
Subscription CancellationsGet a list of customer initiated cancellations and their reasons.Parameterscount 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.
|
RequestGET https://api.chargedesk.com/v1/log/cancellations Example Response{
"count": 2,
"offset": 0,
"data": [
{
action: "cancel",
customer_id: "cus-example-WgwN7cPipB",
email: "customer@example.com",
ip: "1.2.3.4",
method: "at_period_end",
occurred: 1732242969,
reason: "Example cancellation for demonstration purposes",
subscription_id: "sub-example-KbEZslj29A"
},
... more data items here ...
]
}
|
|
API AuthenticationThe 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). |
RequestGET https://api.chargedesk.com/v1/charges Example PHP Code// Include the PHP library
include_once "chargedesk-php/bootstrap.php";
// Set your secret key
ChargeDesk::apiKey("YOUR_SECRET_KEY");
// Perform API request
$charges = ChargeDesk_Charge::find(array(
"count" => "2",
));
|
|
Rate LimitingPlease 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. |
||
MetadataArbitrary 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 DuplicatesCharges, 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 CurrenciesBelow 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 |