Config Tips: Customers

API Call 1 of 2: Create Customer#

name_first name_last phone_number ...#

See full list of customer details at our API Reference. These are standard details that should be available from your approval and KYC process


Optional. This lets you differentiate between businesses and standard consumers, depending on if your business model is B2B, B2C, or both.


Optional. If you are assigning the customer to one or more existing accounts, you can let Canopy know which accounts. For most workflows, we recommend not including this parameter in the create_customer call, and instead assigning an existing customer to an account in the next API call

API Call 2 of 2: Create Account#


Optional. This indicates when the account should be considered originated within Canopy. If you are running a migration, for instance, you may provide a backdated effective_at. If the account is being onboarded in real-time, you may simply omit this parameter, and Canopy will use the current timestamp.

product_id external_product_id#

Provide one or the other. Both have uniqueness enforced. This lets Canopy know which product to enroll the account in. The account inherits the product's configurations, such as its billing cycle policies.


Optional. You may have additional data you want to load into Canopy that is not available in Canopy's API. Simply pass this data into the external_fields section of Canopy.

Payment Processor Config#

Only provide this if you are using one of Canopy's out-of-the-box payment processor integrations.

If you are handling payment processing outside of Canopy, you can simply not pass this entire section in your Create Account call.

If you are interested in using one of our payment processor integrations, check out the payment processor section of our knowledge base.

We highly recommend using our payment processor integrations if you are considering any of our integrated payment processors because they handle the entire payments flow magically for you.


This lets Canopy know whether to look at the borrower's (tokenized) debit card on file or (tokenized) ACH configuration when asking the processor to process payments for the borrower.


This lets Canopy know to automatically trigger payments using the configured payment processor method, whenever the borrower has a minimum payment due.

ach debit card#

Pass details to set up one or both payment processor methods for the borrower

Cycle Type#


This dictates when the borrower's first cycle ends. An example is if you want the borrower's cycle to end every Thursday, and the product is on a weekly cycle, but you onboard them on Tuesday. You can set a 2 day first_cycle_interval (or a 9 day one if you'd like their first cycle to be longer), and this ensures that all subsequent cycles end on Thursdays.



Optional. only pass it if it makes sense for your business model. Passing a loan_discount_cents and a loan_discount_at indicates that if the borrower has paid down the discount amount by the provided date, the remainder of their loan will be waived as a prepayment incentive.


Here you can set some general info about the account.


Optional. If applicable, pass unique credit limits for each of your borrowers based on your risk metrics.


Optional. This is a static field. It helps your servicing agents spot-check whether they can safely increase a credit limit for a borrower without re-approval (if applicable to your business model).

late_fee_cents payment_reversal_fee_cents origination_fee_cents annual_fee_cents monthly_fee_cents#

These are various types of fees you can charge the borrower


This parameter is very important for installment loans. This dictates the total amount you're lending out to the borrower.

Promo Overview#

The lifecycle of all products in Canopy is currently broken into two sections: a promotional, and a post-promotional section. At the moment, only the promotional period can be revolving, and only the post-promotional period can be an amortizing installment loan. (Note, this still allows for pure installment or revolving products by setting a zero-length or infinite-length promotional period respectively.)

In the future, revolving/amortizing characteristics will be independent of whether the product is in the promotional or post-promotional period and products will be able to flex into promotions dynamically.


Optional. This is the interest rate applied during the promotional period. Of course, if you are onboarding the borrower onto a pure installment product, you can simply not pass this argument.

Post-Promo Overview#

As of now, post-promotional periods can only be amortizing installment loans. If there was a promotional period at the time of conversion to the post-promotional period, all charges will be rolled into an installment loan.


Optional. This is the interest rate applied during the post-promotional period. Of course, if you are onboarding the borrower onto a pure revolving product, you can simply not pass this argument.


Optional. This indicates the term of the borrower's installment loan in cycles. Of course, if you are onboarding the borrower onto a pure revolving product, you can simply not pass this argument.

Associated Entities#

merchant_name lender_name#

Optional. These are purely static fields you can associate with the account as metadata

Assign Customers#

Using the customer ID from the response body of the first step, you can assign them to the account you're creating in this request. This allows you to fully onboard the borrower to the account.