The Clover Ecommerce API provides access points for retrieving and working with data in several categories. This topic describes these categories and provides insight into their relationships. Developers using the API should understand the basics of these concepts before investing development time in a Clover app.

Data model

There are four basic elements to the data model, each with an associated endpoint: charges, customers, refunds, and orders. These elements and their relationships are described in the following sections. See the Ecommerce Service API for information.

Charges

A charge is the central action taken with the API. When your application needs to process a payment, you will use a /charges endpoint to perform the transaction. The payment is charged to a source, a credit card or debit card that has been tokenized with the hosted tokenizer. See Integration types for more information.

The charge is related to other data in the following ways:

• A charge is associated with single customer
• A charge is associated with a single order
• A charge can be partially or fully refunded

Customers

Customers will use your application to make payments for products or services provided by a merchant. Customer accounts are uniquely identified by the id field, and other relevant customer data includes their name, address, email, and billing and shipping information.

Cards on file are encrypted tokens stored as sources for the customer’s account. These tokens are retrieved using the hosted tokenizer to keep applications out of PCI scope.

A customer is related to other data in the following ways:

• A customer can have zero or more orders
• A customer can have zero or more charges applied to their account

Refunds

Refunds store information about the partial or full repayment of a charge. The money to be refunded is set with the amount field. Refunds can also set a reason: duplicate, fraudulent, or requested_by_customer.

A refund is related to other data in the following ways:

• A refund is associated with a single charge
• A refund is associated with a single order
• A customer may have zero or many refunds for an order

Orders

Orders store information about the items being purchased, the amount the merchant is charging the customer for those items, and the time the order is created. The customer is likely making the purchase through a website, so the order also contains shipping information. This shipping information may be different from the customer’s billing address or own shipping address. If any of the items are returned, that information is also stored with the order.

An order is related to other data as follows:

• A customer can have zero or more orders
• An order can have a single charge
• An order is made by a single customer

Get started

Use the following Ecommerce APIs to handle the payment flow: