{
"version": "v1",
"groups": [
{
"name": "Gateway Methods",
"commands": [
{
"code": {
"define": {
"method": "POST",
"path": "gateway/products/charge"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Product::charge",
"params": ["{request}"],
"return": "$response",
"additional": [
"// $response->charge now contains the created Charge",
"echo $response->charge->support_url; // print the support url for this charge"
]
}
},
"request": {
"using": "card",
"customer": {
"id": "{example_customer_id}"
},
"amount": "34.00",
"currency": "{local_currency}"
},
"response": "{charge: {example_charge}}"
},
"description": {
"gateway": true,
"title": "Create Charge",
"summary": "Creates a charge in your connected gateway and returns the created object. Add the billing support URL to invoices and receipts so you know exactly what charge a customer is asking a question about.",
"params": {
"using": {
"required": true,
"summary": "Must be set to 'card'."
},
"customer[id]": {
"required": true,
"summary": "The ID of the customer you would like to charge.",
"example": "example@chargedesk.com"
},
"amount": {
"required": true,
"summary": "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": true,
"summary": "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": "{local_currency}",
"refer_to": "api-docs#information-supported-currencies"
},
"description": {
"summary": "Describes what this charge is for. Can be shown on receipts and invoices."
},
"metadata[key]": {
"summary": "Set arbitrary metadata on this charge.",
"refer_to": "api-docs#information-metadata"
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "gateway/products/charge"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Product::charge",
"params": ["{request}"],
"return": "$response",
"additional": [
"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)"
]
}
},
"request": {
"using": "card",
"customer": {
"id": "{example_customer_id}"
},
"amount": "34.00",
"currency": "{local_currency}",
"product": {
"interval": "month",
"trial_period_days": 14
}
},
"response": "{subscription: {example_subscription}, charge: {example_charge}}"
},
"description": {
"gateway": true,
"title": "Create Subscription",
"summary": "Create a subscription for an existing customer using their card on file.",
"params": {
"using": {
"required": true,
"summary": "Must be set to 'card'."
},
"amount": {
"required": true,
"summary": "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": true,
"summary": "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": "{local_currency}",
"refer_to": "api-docs#information-supported-currencies"
},
"quantity": {
"summary": "The number of times this amount is applied. If provided, it must be a whole number great than 1.",
"example": "2"
},
"description": {
"summary": "Describes what this charge is for. Can be shown on receipts and invoices."
},
"customer[id]": {
"required": true,
"summary": "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]": {
"summary": "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": true,
"summary": "Choose how frequently the subscription is charged. Possible values are day, week, month or year."
},
"product[interval_count]": {
"default": 1,
"summary": "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]": {
"summary": "The number of days which the trial period lasts. Enter 0 for none. Must be a positive integer."
},
"product[coupon]": {
"summary": "A coupon to apply agains this product. Must match a coupon ID in your payment gateway."
},
"product[billing_cycles_total]": {
"summary": "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]": {
"summary": "An additional amount to charge when the subscription is initially created. Has the same requirements as the 'amount' field."
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "gateway/products/charge"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Product::charge",
"params": ["{request}"],
"return": "$request",
"additional": [
"// $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)"
]
}
},
"request": {
"contact": "jane@example.com",
"amount": "34.00",
"currency": "{local_currency}"
},
"response": "{pay_link: \"https://chargedesk.com/pay/xxxxx\", charge: {example_charge}}"
},
"description": {
"gateway": true,
"title": "Request Payment",
"summary": "Request a payment from a customer. Can be used to create once off charges, or charges for existing products including recurring charges.",
"params": {
"using": {
"summary": "Can be set to 'invoice' to indicate this is a payment request and not charging a card on file."
},
"contact": {
"summary": "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": {
"default": "false",
"summary": "Generates a link to the payment page and does not automatically send an email or SMS to the contact."
},
"amount": {
"required": true,
"summary": "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": true,
"summary": "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": "{local_currency}",
"refer_to": "api-docs#information-supported-currencies"
},
"quantity": {
"summary": "The number of times this amount is applied. If provided, it must be a whole number great than 1.",
"example": "2"
},
"description": {
"summary": "Describes what this charge is for. Can be shown on receipts and invoices."
},
"customer[id]": {
"summary": "If this invoice is being sent to an existing customer, this field should be used to tie the charge to that customer."
},
"lines[][amount]": {
"summary": "A line item shown on the invoice. The amount of this line item."
},
"lines[][currency]": {
"summary": "A line item shown on the invoice. The currency of this line item."
},
"lines[][quantity]": {
"summary": "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]": {
"summary": "A line item shown on the invoice. Used to associated a line item with a product."
},
"lines[][description]": {
"summary": "A line item shown on the invoice. The description shown on the invoice for this line item."
},
"lines[][taxable]": {
"summary": "A line item shown on the invoice. Is this line item taxable?"
},
"lines[][interval]": {
"summary": "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]": {
"default": 1,
"summary": "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]": {
"summary": "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]": {
"summary": "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]": {
"summary": "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]": {
"summary": "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."
},
"opt_in_product_ids[]": {
"summary": "A product IDs to display as optional add‑ons at checkout. The product is shown, but not preselected by default."
},
"opt_out_product_ids[]": {
"summary": "A product IDs to display as optional add‑ons at checkout. The product is shown and is preselected by default."
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "gateway/charges/{CHARGE_ID}/refund"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Charge::refund",
"params": ["{CHARGE_ID}"],
"return": "$charge"
}
},
"request": {
"amount": "21.00"
},
"response": "{example_charge_refunded}"
},
"description": {
"gateway": true,
"title": "Refund Charge",
"summary": "Process a refund for a charge. Will return a success of failure from the originating payment gateway.",
"params": {
"amount": {
"summary": "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": {
"summary": "Provide a reason to be logged in the activity log this refund"
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "gateway/charges/{CHARGE_ID}/capture"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Charge::capture",
"params": ["{CHARGE_ID}"],
"return": "$charge"
}
},
"request": {
"amount": "34.00"
},
"response": "{example_charge}"
},
"description": {
"gateway": true,
"title": "Capture Charge",
"summary": "Capture or void an authorized charge. Will return a success of failure from the originating payment gateway.",
"params": {
"amount": {
"summary": "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"
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "gateway/subscriptions/{SUBSCRIPTION_ID}/cancel"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Subscription::cancel",
"params": ["{SUBSCRIPTION_ID}"],
"return": "$subscription"
}
},
"response": "{example_subscription_canceled}"
},
"description": {
"gateway": true,
"title": "Cancel Subscription",
"summary": "Cancels any future recurring charges through original payment gateway it was created. May not be supported on all gateways.",
"params": {
"log_reason": {
"summary": "Provide a reason to be logged in the activity log this refund"
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "gateway/subscriptions/{SUBSCRIPTION_ID}/plans"
},
"lang": {
},
"response": "{example_subscription}"
},
"description": {
"gateway": true,
"title": "Edit Subscription Plans",
"summary": "Edits a subscription's plans and recurring details. Not be supported on all gateways.",
"params": {
"plans[][id]": {
"summary": "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]": {
"summary": "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": {
"summary": "Unix timestamp for when the subscription's trial ends. Stripe only.",
"example": "{time_now}"
},
"period_end": {
"summary": "Unix timestamp for when the subscription's current period ends. Recurly only.",
"example": "{time_now}"
},
"prorate": {
"summary": "Prorate any plans changes. Stripe only.",
"example": "true"
},
"invoice": {
"summary": "Invoice any plans changes immediately instead of at period end. Stripe & Recurly only.",
"example": "true"
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "gateway/charges/{CHARGE_ID}/void"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Charge::void",
"params": ["{CHARGE_ID}"],
"return": "$charge"
}
},
"response": "{example_charge}"
},
"description": {
"gateway": true,
"title": "Cancel Payment Request",
"summary": "Cancel the payment request. The payment page will show that the charge no longer needs to be paid."
}
}
]
},
{
"name": "Charges",
"commands": [
{
"code": {
"define": {
"method": "POST",
"path": "charges"
},
"lang": {
"php": {
"command": "ChargeDesk_Charge::create",
"params": ["{request}"],
"return": "$charge",
"additional": [
"// $charge now contains the created Charge",
"echo $charge->support_url; // print the support url for this charge"
]
}
},
"request": {
"amount": "34.00",
"currency": "{local_currency}",
"customer": {
"id": "{example_customer_id}"
}
},
"response": "{example_charge}"
},
"description": {
"title": "Create",
"summary": "Creates a record of an external charge. NB: this is not a gateway method, so will not create a live charge on your gateway. Use the Create Charge gateway method to create a live charge.",
"params": {
"amount": {
"required": true,
"summary": "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": true,
"summary": "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": "{local_currency}",
"refer_to": "api-docs#information-supported-currencies"
},
"gateway_id": {
"summary": "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": {
"default": "The current time since epoch will be used.",
"summary": "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": true,
"summary": "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]": {
"summary": "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]": {
"summary": "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]": {
"summary": "Full name of the customer who this charge is for.",
"example": "James Peter"
},
"customer[description]": {
"summary": "Some additional information useful in describing this customer to support agents."
},
"customer[delinquent]": {
"default": false,
"summary": "Is there a problem with the payments of this customer not being processed?"
},
"customer[country]": {
"summary": "Two-letter ISO code of the country where the customer is located.",
"example": "US"
},
"status": {
"default": "paid",
"summary": "The current state of this charge. Can be {charge_types}."
},
"amount_refunded": {
"summary": "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": {
"summary": "Last 4 digits of the credit card used to create this charge."
},
"transaction_id": {
"summary": "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": {
"summary": "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": "api-docs#information-handling-duplicates"
},
"description": {
"summary": "A short string describing what this charge is for. Displayed to users when they are querying why a charge was made."
},
"product[id]": {
"summary": "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]": {
"summary": "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]": {
"summary": "A line item shown on the invoice. The amount of this line item."
},
"lines[][currency]": {
"summary": "A line item shown on the invoice. The currency of this line item."
},
"lines[][quantity]": {
"summary": "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]": {
"summary": "A line item shown on the invoice. Used to associated a line item with a product."
},
"lines[][description]": {
"summary": "A line item shown on the invoice. The description shown on the invoice for this line item."
},
"lines[][taxable]": {
"summary": "A line item shown on the invoice. Is this line item taxable?"
},
"lines[][tax_paid]": {
"summary": "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]": {
"summary": "Set arbitrary metadata on this charge.",
"refer_to": "api-docs#information-metadata"
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "charges"
},
"lang": {
"php": {
"command": "ChargeDesk_Charge::find",
"params": ["{request}"],
"return": "$charges"
}
},
"request": {
"count": 2
},
"response": "{example_list_open}{example_charge}{example_list_close}"
},
"description": {
"title": "List all",
"summary": "Get all charges associated with the secret key provided in the request",
"params": {
"count": {
"default": "20",
"summary": "Number of charges to return per request in the response. Must be between 1 and 500."
},
"offset": {
"default": "0",
"summary": "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": {
"summary": "Only return charges in a certain state. Can be {charge_types}"
},
"query": {
"summary": "Only return charges which match the given query. The query will run against any searchable field."
},
"customer[id]": {
"summary": "Only return charges from customers matching this customer id."
},
"customer[email]": {
"summary": "Only return charges from customers matching this email."
},
"customer[name]": {
"summary": "Only return charges from customers matching this name."
},
"customer[username]": {
"summary": "Only return charges from customers matching this username."
},
"last_4_digits": {
"summary": "Only return charges with customers matching these last 4 digits on their card."
},
"description": {
"summary": "Only return charges with customers matching this description."
},
"transaction_id": {
"summary": "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]": {
"summary": "Maximum seconds since epoch (unix timestamp) that charges must have occurred before."
},
"occurred[min]": {
"summary": "Minimum seconds since epoch (unix timestamp) that charges must have occurred after."
},
"metadata_key": {
"summary": "Only return charges which have metadata with this key."
},
"metadata_value": {
"summary": "Only return charges which have metadata with this value."
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "charges/{CHARGE_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Charge::retrieve",
"params": ["{CHARGE_ID}"],
"return": "$charge"
}
},
"response": "{example_charge}"
},
"description": {
"title": "Retrieve",
"summary": "Retrieves a charge that has previously been created."
}
},
{
"code": {
"define": {
"method": "GET",
"path": "charges/{CHARGE_ID}/items"
},
"response": "{example_charge_items}"
},
"description": {
"title": "Retrieve Items",
"summary": "Retrieves charge items."
}
},
{
"code": {
"define": {
"method": "POST",
"path": "charges/{CHARGE_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Charge::update",
"params": [
"{CHARGE_ID}",
"{request}"
],
"return": "$charge"
}
},
"request": {
"status": "paid"
},
"response": "{example_charge}"
},
"description": {
"title": "Update",
"summary": "Updates an existing charge with new information.",
"params": {
"amount": {
"summary": "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": {
"summary": "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": "{local_currency}",
"refer_to": "api-docs#information-supported-currencies"
},
"occurred": {
"default": "The current time since epoch will be used.",
"summary": "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": true,
"summary": "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]": {
"summary": "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]": {
"summary": "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]": {
"summary": "Full name of the customer who this charge is for.",
"example": "James Peter"
},
"customer[description]": {
"summary": "Some additional information useful in describing this customer to support agents."
},
"customer[delinquent]": {
"default": false,
"summary": "Is there a problem with the payments of this customer not being processed?"
},
"customer[country]": {
"summary": "Two-letter ISO code of the country where the customer is located.",
"example": "US"
},
"status": {
"default": "paid",
"summary": "The current state of this charge. Can be {charge_types}."
},
"amount_refunded": {
"summary": "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": {
"summary": "Last 4 digits of the credit card used to create this charge."
},
"transaction_id": {
"summary": "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": {
"summary": "A short string describing what this charge is for. Displayed to users when they are querying why a charge was made."
},
"product[id]": {
"summary": "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]": {
"summary": "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]": {
"summary": "A line item shown on the invoice. The amount of this line item."
},
"lines[][currency]": {
"summary": "A line item shown on the invoice. The currency of this line item."
},
"lines[][quantity]": {
"summary": "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]": {
"summary": "A line item shown on the invoice. Used to associated a line item with a product."
},
"lines[][description]": {
"summary": "A line item shown on the invoice. The description shown on the invoice for this line item."
},
"lines[][taxable]": {
"summary": "A line item shown on the invoice. Is this line item taxable?"
},
"lines[][tax_paid]": {
"summary": "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]": {
"summary": "Set arbitrary metadata on this charge.",
"refer_to": "api-docs#information-metadata"
}
}
}
},
{
"code": {
"define": {
"method": "POST",
"path": "charges/{CHARGE_ID}/email"
},
"lang": {
"php": {
"command": "ChargeDesk_Gateway_Charge::email",
"params": ["{CHARGE_ID}"],
"return": "$charge"
}
},
"request": {
"email": "example@customer.com"
}
},
"description": {
"title": "Email Charge",
"summary": "Send an email notification (such as receipt) to the customer. The type of email sent will depend on the current status of the charge. Paid or Pending charges will send a receipt. Refunded charges will send a refund notification. Authorized charges will send an authorized notification. Voided charges will send a void email.",
"params": {
"email": {
"summary": "The email address to send the notification to.",
"example": "example@customer.com"
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "charges/preview"
},
"request": {
"charge_id": "{example_charge_id}",
"amount": "10.00",
"currency": "USD",
"country": "US"
},
"response": {
"subtotalAmount": 10.00,
"subtotalAmountFormatted": "$10.00",
"taxRates": [
{
"name": "Tax",
"rate": 10,
"amount": 1.00,
"amountFormatted": "$1.00"
}
],
"totalAmount": 11.00,
"totalAmountFormatted": "$11.00"
}
},
"description": {
"title": "Preview Charge",
"summary": "Preview the subtotal, any tax rates and the final total amount for a charge or product. Calculations are based on the country and tax ID provided. Useful for previews in checkout forms.",
"params": {
"charge_id": {
"summary": "The charge to preview."
},
"product_id": {
"summary": "The product to preview. Ignored if a charge_id is also provided."
},
"amount": {
"summary": "The amount to preview. Required if no charge or product is provided, otherwise will override the amount for the charge or product."
},
"currency": {
"summary": "The currency to preview. Required if no charge or product is provided, otherwise will override the currency for the charge or product."
},
"country": {
"summary": "Two-letter ISO code of the country where the customer is located.",
"example": "US"
},
"tax_number": {
"summary": "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": {
"summary": "Override the company setting for if tax is added to the final amount, or included in it."
}
}
}
},
{
"code": {
"define": {
"method": "DELETE",
"path": "charges/{CHARGE_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Charge::delete",
"params": [
"{CHARGE_ID}"
],
"return": "$result"
}
}
},
"description": {
"title": "Delete",
"summary": "Deletes a charge record."
}
}
]
},
{
"name": "Customers",
"commands": [
{
"code": {
"define": {
"method": "POST",
"path": "customers"
},
"lang": {
"php": {
"command": "ChargeDesk_Customer::create",
"params": ["{request}"],
"return": "$customer"
}
},
"request": {
"customer_id": "{example_customer_id}",
"country": "US"
},
"response": "{example_customer}"
},
"description": {
"title": "Create",
"summary": "Used to tie all charges from the same person together.",
"params": {
"customer_id": {
"required": true,
"summary": "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": {
"summary": "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": "api-docs#information-handling-duplicates"
},
"gateway_id": {
"summary": "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": {
"summary": "Email address of the customer who this charge is for. Optional, but highly recommended."
},
"country": {
"summary": "Two-letter ISO code of the country where the customer is located.",
"example": "US"
},
"name": {
"summary": "Full name of the customer who this charge is for.",
"example": "Jane Customer"
},
"phone": {
"summary": "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": {
"summary": "A username associated with this customer.",
"example": "janecustomer"
},
"customer_company": {
"summary": "A company name or ID associated with the customer."
},
"website": {
"summary": "A website associated with the customer."
},
"description": {
"summary": "A description of up to 255 characters for the customer. "
},
"delinquent": {
"summary": "Is the customer past due on their payments?",
"example": "false"
},
"card_on_file": {
"summary": "Does the customer have a card on file which can be charged?",
"example": "true"
},
"tax_number_abr": {
"summary": "Tax ID Abbreviation. Generally 3-4 letters such as GST or VAT.",
"example": "VAT"
},
"tax_number": {
"summary": "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": {
"summary": "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\nLondon, United Kingdom"
},
"shipping_address": {
"summary": "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\nLondon, United Kingdom"
},
"invoice_details": {
"summary": "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\nLondon, United Kingdom"
},
"metadata[key]": {
"summary": "Set arbitrary metadata on this customer.",
"refer_to": "api-docs#information-metadata"
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "customers"
},
"lang": {
"php": {
"command": "ChargeDesk_Customer::find",
"params": ["{request}"],
"return": "$customers"
}
},
"request": {
"count": 2
},
"response": "{example_list_open}{example_customer}{example_list_close}"
},
"description": {
"title": "List all",
"summary": "Get all customers associated with the secret key provided in the request",
"params": {
"count": {
"default": "20",
"summary": "Number of customers to return per request in the response. Must be between 1 and 500."
},
"offset": {
"default": "0",
"summary": "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": {
"summary": "Only return customers matching this customer id."
},
"email": {
"summary": "Only return customers matching this email."
},
"name": {
"summary": "Only return customers matching this name."
},
"username": {
"summary": "Only return customers matching this username."
},
"country": {
"summary": "Only return customers matching this country."
},
"first_seen[max]": {
"summary": "Maximum seconds since epoch (unix timestamp) that customer must have been created before."
},
"first_seen[min]": {
"summary": "Minimum seconds since epoch (unix timestamp) that customer must have been created after."
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "customers/{CUSTOMER_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Customer::retrieve",
"params": ["{CUSTOMER_ID}"],
"return": "$customer"
}
},
"response": "{example_customer}"
},
"description": {
"title": "Retrieve",
"summary": "Retrieves a customer that has previously been created."
}
},
{
"code": {
"define": {
"method": "POST",
"path": "customers/{CUSTOMER_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Customer::update",
"params": [
"{CUSTOMER_ID}",
"{request}"
],
"return": "$customer"
}
},
"request": {
"username": "janecustomer"
},
"response": "{example_customer}"
},
"description": {
"title": "Update",
"summary": "Update the data stored for an existing customer.",
"params": {
"customer_id": {
"summary": "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": {
"summary": "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": {
"summary": "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.",
"default": "false"
},
"email": {
"summary": "Email address of the customer who this charge is for. Optional, but highly recommended."
},
"send_email_to": {
"summary": "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": {
"summary": "Two-letter ISO code of the country where the customer is located.",
"example": "US"
},
"name": {
"summary": "Full name of the customer who this charge is for.",
"example": "Jane Customer"
},
"phone": {
"summary": "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": {
"summary": "A username associated with this customer.",
"example": "janecustomer"
},
"customer_company": {
"summary": "A company name or ID associated with the customer."
},
"website": {
"summary": "A website associated with the customer."
},
"description": {
"summary": "A description of up to 255 characters for the customer. "
},
"delinquent": {
"summary": "Is the customer past due on their payments?",
"example": "false"
},
"card_on_file": {
"summary": "Does the customer have a card on file which can be charged?",
"example": "true"
},
"tax_number_abr": {
"summary": "Tax ID Abbreviation. Generally 3-4 letters such as GST or VAT.",
"example": "VAT"
},
"tax_number": {
"summary": "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": {
"summary": "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\nLondon, United Kingdom"
},
"shipping_address": {
"summary": "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\nLondon, United Kingdom"
},
"invoice_details": {
"summary": "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\nLondon, United Kingdom"
},
"metadata[key]": {
"summary": "Set arbitrary metadata on this customer.",
"refer_to": "api-docs#information-metadata"
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "customers/grouped"
},
"lang": {
"php": {
"command": "ChargeDesk_Customer::grouped",
"params": ["{request}"],
"return": "$grouped"
}
},
"request": {
"customer[email]": "james@example.com"
}
},
"description": {
"title": "Grouped",
"summary": "Gets the structured billing history for a customer. Used for assisting agents to solve support requests. As much data as possible should be provided for most accurate results.",
"params": {
"customer[id]": {
"summary": "Looks for customers & charges matching this id"
},
"customer[email]": {
"summary": "Looks for customers & charges matching this email."
},
"customer[username]": {
"summary": "Looks for customers & charges matching this username."
},
"customer[name]": {
"summary": "Looks for customers & charges matching this name."
},
"customer[phone]": {
"summary": "Looks for customers & charges matching this phone number."
},
"query": {
"summary": "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."
}
}
}
},
{
"code": {
"define": {
"method": "DELETE",
"path": "customers/{CUSTOMER_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Customer::delete",
"params": [
"{CUSTOMER_ID}"
],
"return": "$result"
}
}
},
"description": {
"title": "Delete",
"summary": "Deletes a customer record.",
"params": {
"delete_all": {
"default": "1",
"summary": "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."
}
}
}
}
]
},
{
"name": "Subscriptions",
"commands": [
{
"code": {
"define": {
"method": "POST",
"path": "subscriptions"
},
"lang": {
"php": {
"command": "ChargeDesk_Subscription::create",
"params": ["{request}"],
"return": "$subscription"
}
},
"request": {
"subscription_id": "{example_subscription_id}",
"customer_id": "{example_customer_id}",
"amount": "34.00",
"currency": "{local_currency}",
"interval": "month"
},
"response": "{example_subscription}"
},
"description": {
"title": "Create",
"summary": "Creates a record of an external subscription. NB: this is not a gateway method, so will not create a live subscription on your gateway. Use the Create Subscription gateway method to create a live subscription.",
"params": {
"subscription_id": {
"required": true,
"summary": "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": {
"summary": "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": "api-docs#information-handling-duplicates"
},
"customer_id": {
"summary": "The ID of the customer that this subscription is associated with."
},
"status": {
"default": "active",
"summary": "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": {
"summary": "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": {
"summary": "The amount that this subscription is for. Must be a decimal value."
},
"currency": {
"summary": "The currency that this subscription uses.",
"refer_to": "api-docs#information-supported-currencies"
},
"setup_amount": {
"summary": "Additional amount charged when subscription is first created. Must be a decimal value."
},
"product_id": {
"summary": "If defined, needs to match the ID of a product you have created or imported to ChargeDesk."
},
"interval": {
"summary": "How frequently the subscription is charged. Possible values are day, week, month or year.",
"example": "month"
},
"interval_count": {
"summary": "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": {
"summary": "The number of times this amount is applied. If provided, it must be a whole number great than 1.",
"example": "2"
},
"current_period_start": {
"summary": "When the current billing cycle started. In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"current_period_end": {
"summary": "When the current billing cycle will end. In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"trial_start": {
"summary": "When the trial period started (if status is trailing). In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"trial_end": {
"summary": "When the trial period will end (if status is trailing). In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"ended_at": {
"summary": "When the subscription ended (if not cancelled). In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"canceled_at": {
"summary": "When the subscription was cancelled. In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"billing_cycles_total": {
"summary": "Total number of billing cycles for this subscription.",
"example": "10"
},
"billing_cycles_current": {
"summary": "Current billing cycle for this subscription.",
"example": "2"
},
"items[][id]": {
"summary": "The ID of this subscription item."
},
"items[][amount]": {
"summary": "The amount of this subscription item."
},
"items[][currency]": {
"summary": "The currency of this subscription item."
},
"items[][quantity]": {
"summary": "The quantity of this subscription item."
},
"items[][percent]": {
"summary": "If the subscription item represents a discount, this defines the percentage discount."
},
"items[][description]": {
"summary": "The description of this subscription item."
},
"metadata[key]": {
"summary": "Set arbitrary metadata on this subscription.",
"refer_to": "api-docs#information-metadata"
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "subscriptions"
},
"lang": {
"php": {
"command": "ChargeDesk_Subscription::find",
"params": ["{request}"],
"return": "$subscriptions"
}
},
"request": {
"count": 2
},
"response": "{example_list_open}{example_subscription}{example_list_close}"
},
"description": {
"title": "List all",
"summary": "Get all subscriptions associated with the secret key provided in the request",
"params": {
"count": {
"default": "20",
"summary": "Number of subscriptions to return per request in the response. Must be between 1 and 500."
},
"offset": {
"default": "0",
"summary": "Position to start returning subscriptions from. Used to paginate through all subscriptions. Must be between 0 and 10,000."
},
"customer_id": {
"summary": "Only return subscriptions matching this customer id."
},
"created[max]": {
"summary": "Maximum seconds since epoch (unix timestamp) that subscription must have been created before."
},
"created[min]": {
"summary": "Minimum seconds since epoch (unix timestamp) that subscription must have been created after."
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "subscriptions/{SUBSCRIPTION_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Subscription::retrieve",
"params": ["{SUBSCRIPTION_ID}"],
"return": "$subscription"
}
},
"response": "{example_subscription}"
},
"description": {
"title": "Retrieve",
"summary": "Retrieves a subscription that has previously been created."
}
},
{
"code": {
"define": {
"method": "POST",
"path": "subscriptions/{SUBSCRIPTION_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Subscription::update",
"params": [
"{SUBSCRIPTION_ID}",
"{request}"
],
"return": "$subscription"
}
},
"request": {
"status": "active"
},
"response": "{example_subscription}"
},
"description": {
"title": "Update",
"summary": "Update the data stored for an existing subscription.",
"params": {
"subscription_id": {
"summary": "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": {
"summary": "The ID of the customer that this subscription is associated with."
},
"status": {
"default": "active",
"summary": "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": {
"summary": "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": {
"summary": "The amount that this subscription is for. Must be a decimal value."
},
"currency": {
"summary": "The currency that this subscription uses.",
"refer_to": "api-docs#information-supported-currencies"
},
"setup_amount": {
"summary": "Additional amount charged when subscription is first created. Must be a decimal value."
},
"product_id": {
"summary": "If defined, needs to match the ID of a product you have created or imported to ChargeDesk."
},
"interval": {
"summary": "How frequently the subscription is charged. Possible values are day, week, month or year.",
"example": "month"
},
"interval_count": {
"summary": "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": {
"summary": "The number of times this amount is applied. If provided, it must be a whole number great than 1.",
"example": "2"
},
"current_period_start": {
"summary": "When the current billing cycle started. In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"current_period_end": {
"summary": "When the current billing cycle will end. In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"trial_start": {
"summary": "When the trial period started (if status is trailing). In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"trial_end": {
"summary": "When the trial period will end (if status is trailing). In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"ended_at": {
"summary": "When the subscription ended (if not cancelled). In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"canceled_at": {
"summary": "When the subscription was cancelled. In seconds since epoch (unix timestamp).",
"example": "{time_now}"
},
"billing_cycles_total": {
"summary": "Total number of billing cycles for this subscription.",
"example": "10"
},
"billing_cycles_current": {
"summary": "Current billing cycle for this subscription.",
"example": "2"
},
"items[][id]": {
"summary": "The ID of this subscription item."
},
"items[][amount]": {
"summary": "The amount of this subscription item."
},
"items[][currency]": {
"summary": "The currency of this subscription item."
},
"items[][quantity]": {
"summary": "The quantity of this subscription item."
},
"items[][percent]": {
"summary": "If the subscription item represents a discount, this defines the percentage discount."
},
"items[][description]": {
"summary": "The description of this subscription item."
},
"metadata[key]": {
"summary": "Set arbitrary metadata on this subscription.",
"refer_to": "api-docs#information-metadata"
}
}
}
}
]
},
{
"name": "Products",
"commands": [
{
"code": {
"define": {
"method": "POST",
"path": "products"
},
"lang": {
"php": {
"command": "ChargeDesk_Product::create",
"params": ["{request}"],
"return": "$product"
}
},
"request": {
"product_id": "{example_product_id}",
"name": "Example Product",
"description": "Example product description",
"amount": "34.00",
"currency": "{local_currency}"
},
"response": "{example_product}"
},
"description": {
"title": "Create",
"summary": "Creates a new product. Products are a general way of associating charges for the same type of sale together.",
"params": {
"product_id": {
"required": true,
"summary": "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": {
"summary": "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": "api-docs#information-handling-duplicates"
},
"name": {
"summary": "The name of the product as your customers will understand it."
},
"description": {
"summary": "A few sentences explaining what the product is. Must be 255 characters or less."
},
"url": {
"summary": "A url where more information can be found about this product, such as a product page on your website."
},
"amount": {
"summary": "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": {
"summary": "A 3 letter code representing the currency charged for this product. Refer to the link below for a list of supported currency codes.",
"example": "{local_currency}",
"refer_to": "api-docs#information-supported-currencies"
},
"quantity": {
"summary": "The number of times this amount is applied. If provided, it must be a whole number great than 1.",
"example": "2"
},
"gateway_id": {
"summary": "The primary gateway associated with this product.",
"example": "stripe"
},
"chargeable": {
"summary": "Can new charges be created for this product? Will also generate a payment page if true.",
"default": "true"
},
"interval": {
"summary": "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": {
"default": 1,
"summary": "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": {
"summary": "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": {
"summary": "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": {
"summary": "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."
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "products"
},
"lang": {
"php": {
"command": "ChargeDesk_Product::find",
"params": ["{request}"],
"return": "$products"
}
},
"request": {
"count": 2
},
"response": "{example_list_open}{example_product}{example_list_close}"
},
"description": {
"title": "List all",
"summary": "Get all products associated with the secret key provided in the request",
"params": {
"count": {
"default": "20",
"summary": "Number of products to return per request in the response. Must be between 1 and 500."
},
"offset": {
"default": "0",
"summary": "Position to start returning products from. Used to paginate through all products. Must be between 0 and 10,000. We recommend using created[max] to paginate earlier than 10,000 products."
},
"created[max]": {
"summary": "Maximum seconds since epoch (unix timestamp) that product must have been created before."
},
"created[min]": {
"summary": "Minimum seconds since epoch (unix timestamp) that product must have been created after."
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "products/{PRODUCT_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Product::retrieve",
"params": ["{PRODUCT_ID}"],
"return": "$product"
}
},
"response": "{example_product}"
},
"description": {
"title": "Retrieve",
"summary": "Retrieves a product that has previously been created."
}
},
{
"code": {
"define": {
"method": "POST",
"path": "products/{PRODUCT_ID}"
},
"lang": {
"php": {
"command": "ChargeDesk_Product::update",
"params": [
"{PRODUCT_ID}",
"{request}"
],
"return": "$product"
}
},
"request": {
"name": "Example Product"
},
"response": "{example_product}"
},
"description": {
"title": "Update",
"summary": "Update the data stored for an existing product.",
"params": {
"product_id": {
"summary": "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": {
"summary": "The name of the product as your customers will understand it."
},
"description": {
"summary": "A few sentences explaining what the product is. Must be 255 characters or less."
},
"url": {
"summary": "A url where more information can be found about this product, such as a product page on your website."
},
"amount": {
"summary": "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": {
"summary": "A 3 letter code representing the currency charged for this product. Refer to the link below for a list of supported currency codes.",
"example": "{local_currency}",
"refer_to": "api-docs#information-supported-currencies"
},
"quantity": {
"summary": "The number of times this amount is applied. If provided, it must be a whole number great than 1.",
"example": "2"
},
"gateway_id": {
"summary": "The primary gateway associated with this product.",
"example": "stripe"
},
"chargeable": {
"summary": "Can new charges be created for this product? Will also generate a payment page if true.",
"default": "true"
},
"interval": {
"summary": "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": {
"default": 1,
"summary": "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": {
"summary": "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": {
"summary": "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": {
"summary": "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."
}
}
}
}
]
},
{
"name": "Webhooks",
"commands": [
{
"code": {
"define": {
"method": "POST",
"path": "webhooks"
},
"lang": {
},
"request": {
"url": "https://yoursite.com/chargedesk-webhook",
"all": 1
},
"response": {
"webhook_id": "{WEBHOOK_ID}"
}
},
"description": {
"title": "Create",
"summary": "Creates a new webhooks.",
"params": {
"url": {
"required": true,
"summary": "A valid URL endpoint for the webhook to send notifications to."
},
"all": {
"summary": "Specify that this webhook should receive all possible notifications."
},
"notifications": {
"summary": "A list of notifications for this webhook to send requests for. A list of all possible notifications can be found below."
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "webhooks/notifications"
},
"lang": {
},
"response": "{example_notifications}"
},
"description": {
"title": "Notifications",
"summary": "Get a list of all possible notifications.
"
}
},
{
"code": {
"define": {
"method": "DELETE",
"path": "webhooks/{WEBHOOK_ID}"
},
"lang": {
}
},
"description": {
"title": "Delete",
"summary": "Delete an existing webhook."
}
}
]
},
{
"name": "Agents",
"commands": [
{
"code": {
"define": {
"method": "POST",
"path": "agents"
},
"lang": {
},
"request": {
"name": "John Example",
"email": "john@example.com",
"role": "agent"
}
},
"description": {
"title": "Create",
"summary": "Creates a new ChargeDesk agent. An email will be sent to the agent inviting them to create a password and setup their ChargeDesk account. If agent already exists their role will be updated.",
"params": {
"name": {
"required": true,
"summary": "Agent name."
},
"email": {
"required": true,
"summary": "Agent email address."
},
"role": {
"required": true,
"summary": "Role for agent. Can be `read-only`, `agent` or `admin`. Custom roles are also supported using the role name."
}
}
}
},
{
"code": {
"define": {
"method": "DELETE",
"path": "agents/{AGENT_EMAIL}"
},
"lang": {
}
},
"description": {
"title": "Delete",
"summary": "Delete an existing ChargeDesk agent with an given email address."
}
}
]
},
{
"name": "Logs",
"commands": [
{
"code": {
"define": {
"method": "GET",
"path": "log/activity"
},
"request": {
"count": 2
},
"response": "{example_list_open}{example_agent_log}{example_list_close}"
},
"description": {
"title": "Agent Activity",
"summary": "Get all products associated with the secret key provided in the request",
"params": {
"count": {
"default": "20",
"summary": "Number of logs to return per request in the response. Must be between 1 and 500."
},
"offset": {
"default": "0",
"summary": "Position to start returning logs from. Used to paginate through all logs. Must be between 0 and 10,000."
},
"object_id": {
"summary": "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": {
"summary": "Only return logs matching a specific object type. Must be 'charge', 'customer', 'subscription' or 'product'.",
"example": "charge"
},
"action_type": {
"summary": "Only return logs matching a specific action. Requires object_type to also be set. ",
"example": "refund"
},
"occurred[max]": {
"summary": "Maximum seconds since epoch (unix timestamp) that logs must have occurred before."
},
"occurred[min]": {
"summary": "Minimum seconds since epoch (unix timestamp) that logs must have occurred after."
}
}
}
},
{
"code": {
"define": {
"method": "GET",
"path": "log/cancellations"
},
"request": {
"count": 2
},
"response": "{example_list_open}{example_subscription_log}{example_list_close}"
},
"description": {
"title": "Subscription Cancellations",
"summary": "Get a list of customer initiated cancellations and their reasons.",
"params": {
"count": {
"default": "20",
"summary": "Number of logs to return per request in the response. Must be between 1 and 500."
},
"offset": {
"default": "0",
"summary": "Position to start returning logs from. Used to paginate through all logs. Must be between 0 and 10,000."
},
"action": {
"summary": "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]": {
"summary": "Maximum seconds since epoch (unix timestamp) that cancellation must have occurred before."
},
"occurred[min]": {
"summary": "Minimum seconds since epoch (unix timestamp) that cancellation must have occurred after."
}
}
}
}
]
},
{
"name": "Information",
"commands": [
{
"code": {
"define": {
"method": "GET",
"path": "charges"
},
"lang": {
"php": {
"command": "ChargeDesk_Charge::find",
"params": ["{request}"],
"return": "$charges"
}
},
"request": {
"count": 2
}
},
"description": {
"title": "API Authentication",
"summary": "The ChargeDesk API is authenticated using HTTP Basic Authentication. Pass your secret key in the basic auth username. A password is not required.
Each company you create on ChargeDesk has their own secret key and must have API access enabled. You can turn on API access for your company and find your secret key at https://chargedesk.com/connect/api
Every piece of example code on the page contains all the authentication information you need. If you login with your account and visit this page, your secret key from the last company you looked at will be filled out for you (if the API is active for that company)."
}
},
{
"description": {
"title": "Rate Limiting",
"summary": "Please limit your API requests to 60 requests per minute. If you make more requests than this, you will be blocked from making another request for 60 seconds.
When your API requests are rate limited, you will receive a 429 response code with a 'Retry-After: X' header to let you know how long until you can try your request again."
}
},
{
"description": {
"title": "Metadata",
"summary": "Arbitrary metadata can be assigned to charges, customers and subscriptions. The metadata is then visible to support agents and returned in future API calls and webhooks.
Metadata should be provided in key, value pairs. Keys may be up to 32 characters, and values up to 255 characters."
}
},
{
"description": {
"title": "Handling Duplicates",
"summary": "Charges, Customers, Subscriptions and Products all have unique IDs (transaction_id for Charges, customer_id for Customers, subscription_id for Subscriptions and product_id for Products). When importing data from your system, you may not always know if the relevant resource has already been imported into ChargeDesk.
When this is the case, to save duplicating API calls, you can set duplicate=update on any of the creation endpoints for these resources. If existing data matching the unique ID for the resource already exists, the request will not fail and instead will update the relevant resource with the latest data."
}
},
{
"description": {
"title": "Supported Currencies",
"summary": "Below is a list of all currency codes supported by ChargeDesk.
Please note that in order to create a charge in a currency, it must be supported by your connected payment gateways.
{supported_currencies}"
}
}
]
}
]
}