This guide describes how to manage a Customer Credit account in your store by performing the following actions through the endpoints of the Customer Credit API:

• Create a Customer Credit account
• Check Customer Credit account details
• Update personal information and credit settings
• Check operations statement
• Register dependents for credit sharing
• Check all Customer Credit accounts of a store
• Close a Customer Credit account

For more information about Customer Credit functionalities, access Customer Credit - Overview and Customer Credit - Getting Started.

To provide exclusive credit to a customer, you can create a Customer Credit account via VTEX Admin or use the Open an account endpoint. In this request, you must send the following customer data and account usage parameters:

• document: Customer document.
• documentType: Document type (CPF, CNPJ, other).
• email: Customer email.
• creditLimit: Maximum credit amount on the account.
• tolerance: Account credit tolerance (in decimals). This value represents the increase in credit on an account. For example, a value of 0.30 indicates that the customer - can use up to 30% above the account's original maximum credit amount.

POST - Open an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts

Request body

The endpoint will return some of the previously sent data and new information about the created account, such as:

• id: Client’s Customer Credit account identification.
• balance: Account balance value. If this number is negative, the account has a debit instead of a credit to be used.
• status: Client’s Customer Credit account status. All accounts are created with the status Open.
• updatedAt: Date of the last update made to the account (UTC format).
• createdAt: Account creation date (UTC format).
• availableCredit: Credit amount available on the account.
• preAuthorizedCredit: Credit value that can only be used by the account owner after the merchant releases a specific purchase transaction.
• availableBalance: Balance available in the account

Response body

You can also access your VTEX Admin (Apps > Customer Credit > Accounts) to confirm that the new Customer Credit account was created.

When the Customer Credit account is created using the Open an account endpoint, the account identification (id) will be composed of information from the document and documentType fields, for example, 55555555555_CPF. If account creation is performed through your VTEX Admin (Apps > Customer credit > Accounts > New), an identification code will be randomly created by the system and will be used as account identification, such as 92bccd01-b4ed-15sa-88a4 -175868a0bf42.

When you want to check details about a specific Customer Credit account, you can use the Retrieve an account by ID endpoint. In this request, you must send the account identification (id) as a path parameter.

See an example below using the account 111111111_CPF:

GET - Retrieve an account by ID

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/111111111_CPF

Response body

You can also check a Customer's Credit account details using the VTEX Admin. For more information, go to Apps > Customer Credit > Accounts and click the desired account.

The Customer Credit API allows you to modify an account settings through the following actions:

• Update account information
• Change credit limit
• Change tolerance

The Update account information endpoint must be used to update the email address, type, and document number registered to the client.

You can also use this endpoint to change the credit limit and tolerance information, but it will be mandatory to send the id, document, and documentId fields, even when you do not intend to update this information. If the id, document, and documentId fields are not sent in this request, the information related to them will be removed from the account.

See an example below using the account fe60ff40-d1cb-11ee-a0ed-87f4fcc03446:

PUT - Update account information

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446

Request body

The endpoint will return the account details with updated information.

Response body

The Change credit limit of an account endpoint must be used when you want to change the credit limit value available to a customer credit account. In this request, you must send the account identification (id) as a path parameter and the value field containing the new credit limit, as shown in the example below:

PUT - Change credit limit of an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/creditlimit

Request body

The endpoint will return the account details and the creditLimit field already updated.

Response body

The Change tolerance of an account endpoint must be used when you want to change the credit tolerance amount available on a customer credit account.

In this request, you must send the account identification (id) as a path parameter and the value field containing the new credit limit. The value is represented by a decimal number, where a value of 0.30 means 30% of tolerance.

See an example below using the account fe60ff40-d1cb-11ee-a0ed-87f4fcc03446 and a tolerance of 15%.

PUT - Change tolerance of an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/tolerance

Request body

The endpoint will return the account details and the tolerance field already updated.

Response body

The Get account statements endpoint can be used to track operations performed on a customer credit account, such as:

• Customer credit limit modification
• Tolerance percentage modification
• Invoice Issuance
• Invoice payment

In this request, you must send the account identification (id) as a path parameter:

GET - Get account statements

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/statements

If you send the id of a new account or one without an operation type, the response body of the request will not present any value, as shown below:

Response body

When the credit limit of a customer credit account is modified via VTEX Admin or through the Change credit limit of an account endpoint, it is possible to identify the new value indicated and when the operation was carried out.

See below a scenario where an initial credit limit USD 10.000 is reduced to USD 9.000 and then increased to USD 12.000. The tolerance value configured on this account is 10%.

FIRST OPERATION: Decreasing credit limit from USD 10.000 to USD 9.000

PUT - Change credit limit of an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/creditlimit

Request body

GET - Get account statements

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/statements

Response body

Note that the value displayed in the value field is indicated by a negative sign and 1100.0, instead of 1000.0 which would correspond to how much the credit limit was reduced. This occurs because the endpoint returns the sum of the amount of the reduced credit limit and the percentage of credit tolerance applied to it, in this case, 10% over 1000.0 (100.0).

SECOND OPERATION: Increasing credit limit from USD 9.000 to USD 12.000

PUT - Change credit limit of an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/creditlimit

Request body

GET - Get account statements

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/statements

Response body

As in the credit limit-reducing operation, the value present in the "value" field (3300.0) is indicated by the sum of the value added to the credit limit (3000.0) and the percentage of credit tolerance applied to the operation, 10% on 3000.0 (300.0).

The "intervalBalance" field is responsible for showing the balance between all amounts reduced and added in operations performed on a customer credit account since its opening. In this case, 2200.0 (3300.0 - 1100.0).

When the credit tolerance value in a customer credit account is modified via VTEX Admin or through the Change tolerance of an account endpoint, it is possible to identify the new value indicated and when the operation was carried out.

See below a scenario where an initial credit tolerance of 10% is reduced to 0%, and then increased to 25%. The credit limit value configured on this account is 5.000.

FIRST OPERATION: Decreasing credit tolerance from 10% to 0%

PUT - Change tolerance of an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/tolerance

Request body

GET - Get account statements

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/statements

Response body

Note that the value displayed in the value field is indicated by a negative sign (reduced tolerance percentage) and 500.0, instead of the percentage value 0. This occurs because the endpoint returns the value referring to the percentage reduced in the operation applied to the total amount of credit limit registered on the account. That is, a 10% tolerance reduction over 5000.0 equals 500.0.

SECOND OPERATION: Increasing credit tolerance from 0% to 25%

PUT - Change tolerance of an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/tolerance

Request body

GET - Get account statements

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/statements

Response body

In the same way, as in the operation in which the tolerance percentage was reduced, the value present in the value field (1250.0) represents the added percentage of 25% applied to the credit limit registered in the account (5000.0).

After the customer makes a purchase in the store using customer credit as a payment method and the order is invoiced, it is possible to check the credit operation information on the Get account statements endpoint.

Unlike situations involving credit limit and tolerance changes, in the response body of this type of operation, the origin field is indicated as invoice and a new object named metadata is shown containing the following information:

• transactionId: Transaction identification.
• orderId: Identification of the order for which the invoice was created.
• numberOfInstallments: Number of invoices created to pay for the transaction. invoices created to pay for the order.

See the example below for the response body information related to the operation of a purchase made worth USD 15.

GET - Get account statements

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/statements

Response body

To confirm when a customer credit invoice has been paid by the customer you can also use the Get account statements endpoint.

See below the response body containing the invoice information after order payment.

GET - Get account statements

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/statements

Response body

You can also share the credit available in a customer account with other customers. To do this, you must add a dependent — also known as an account holder — to the account.

Credit sharing between account holders registered in an account occurs in such a way that the sum of all purchases made by them through Customer Credit cannot exceed the amount of credit available in the account.

To add the new account holder to the customer credit account, use the VTEX Admin or the Add an account holder endpoint. In this request, you must send the account identification (id) as a path parameter.

See an example below using the account fe60ff40-d1cb-11ee-a0ed-87f4fcc03446:

POST - Add an account holder

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/holders

Request body

The endpoint will return information about the creation of the new holder such as:

• level: Holder hierarchy. The value 2 indicates that the holder is a dependent of the account's main holder.
• email: Holder email.
• id: Holder identification.
• createdAt: Date of appointment of the holder.

Response body

You can also access your VTEX Admin (Apps > Customer Credit > Accounts) and click the desired account to verify that the new holder was added.

To remove a holder from a customer credit account and prevent them from using the available credit, you can use the VTEX Admin or the Delete an account holder endpoint. In this request, you must send the account identification (id) and the holder identification (id obtained in the VTEX Admin or in the response body of the Add an account holder endpoint as path parameters.

See an example below using the account fe60ff40-d1cb-11ee-a0ed-87f4fcc03446 and the holder 78d22849ad844ae5a57ef1715de73467:

DEL - Delete an account holder

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/fe60ff40-d1cb-11ee-a0ed-87f4fcc03446/holders/78d22849ad844ae5a57ef1715de73467

The endpoint will return the holder's identification, confirming that it was deleted from the account.

Response body

You can also access your VTEX Admin (Apps > Customer Credit > Accounts) and click on the desired account to verify that the new holder was removed.

To check information about all customer credit accounts registered in your store, you can use the VTEX Admin or the Search all accounts endpoint.

GET - Search all accounts

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/

Response body

The count field displays the number of customer credit accounts registered in the store.

If you wish to stop offering credit to a specific customer, you must close the account through VTEX Admin or the Close an account endpoint. In this request, you must send the account identification (id) as a path parameter.

Additionally, you can use the queries below (individually or combined) in the URL to refine your account search:

• By the location of the accounts in the list (quantity of accounts): ?from={int}&to={int}
• By status: ?status={Open, Closed or Cancelled}
• By email: ?email={string}

If your store has more than 20 customer credit accounts and you do not use any queries in the call, only the first 20 account records will appear in the response body.

See an example below using the account fe60ff40-d1cb-11ee-a0ed-87f4fcc03446:

DEL - Close an account

https://{accountName}.{environment}.com.br/api/creditcontrol/accounts/c5886660-d598-11ee-ac7f-a50b38956bb7

The endpoint will return the information for the account that was deleted, displaying the status field as Closed.

Response body

You can also access your VTEX Admin (Apps > Customer Credit > Accounts) to verify that the account was deleted.

Once closed, a Customer Credit account cannot be reopened again and all invoices, statements, and additional dependents data will be deleted. However, after completing the account closure, if you wish, you can open a new account for the customer using the same email as the closed account.