Account credits

Account credits are a form of currency that is stored on a customer's account. This balance can be awarded through actions such as refunds, or it can additionally be increased by the redemption of gift cards. Customers can apply their account credit balance towards purchases during checkout.

The account credit model

Fields

id

objectId

Unique identifier for the credit.

amount

currencyrequired

Credit amount denominated in currency. Minimum of 0.01.

parent_id

objectIdrequired

The ID of the parent customer.

credit

Credit memo

Expandable list of the customer’s credit transactions.

credit_id

objectId

ID of the credit applied to the customer's account.

currency

string

Three-letter ISO currency code in uppercase. Defaults to the store's base currency.

date_created

dateauto

Date and time the credit was created.

date_updated

dateauto

Date and time the credit was last updated.

giftcard_id

objectId

ID of the gift card used to make the payment, if applicable.

invoice

Invoice

Expandable link to the invoice the credit was applied to, if applicable.

invoice_id

objectId

ID of the invoice the credit was applied to, if applicable.

number

stringauto

Unique incremental number assigned automatically each time an account credit is created.

parent

Account

Expandable link to the parent customer.

payment

Payment

Expandable link to the payment.

payment_id

objectId

Unique identifier for the payment.

reason

string

The reason for the refund.

reason_message

string

A brief message describing the reason for the refund.

refund

Refund

Expandable list of refunds that apply to the credit.

refund_id

objectId

ID of the refund the credit was applied to.

The account credit model

{
  "parent_id": "5ffd413300b58e2a4a017831",
  "payment_id": "61e78cbed7e71014da0f1b2c",
  "amount": 100,
  "reason": "promo",
  "reason_message": "Found a bag of gold in a tree stump."
  "currency": "USD",
  "date_created": "2022-01-19T03:59:58.816Z",
  "number": "101082",
  "id": "61e78cbed7e71014da0f1b87"
}

Create an account credit

Create a new customer account credit. If you wish to generate your own unique ID for the record, it must use BSON ObjectID format for compatibility.

Arguments

amount

currencyrequired

Account credit value. Must be greater than zero.

parent_id

objectIdrequired

Unique identifier for the parent account.

POST/account-credits

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/accounts:credits', {
  parent_id: '621e53a6213eaf013d1fa6b2',
  amount: 17,
  reason: 'refund'
});

Response

{
  "parent_id": "621e53a6213eaf013d1fa6b2",
  "amount": 17,
  "reason": "refund",
  "currency": "USD",
  "date_created": "2022-07-08T20:27:40.199Z",
  "number": "100003",
  "id": "62c8933c5f4ffe00136039f2"
}

Retrieve an account credit

Retrieve an existing account credit using the ID that was returned when created.

Arguments

id

objectId

Unique identifier for the credit.

amount

currencyrequired

Credit amount denominated in currency. Minimum of 0.01.

parent_id

objectIdrequired

The ID of the parent customer.

GET/accounts:credits/:id

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/accounts:credits/{id}', {
});

Response

 {
      "parent_id": "5ffd413300b58e2a4a017831",
      "payment_id": "61e78cbed7e71014da0f1b2c",
      "amount": -19.55,
      "currency": "USD",
      "date_created": "2022-01-19T03:59:58.816Z",
      "number": "101082",
      "id": "61e78cbed7e71014da0f1b87"
    },

Update an account credit

Update an existing account credit using the ID that was returned when created.

Arguments

id

objectId

Unique identifier for the credit.

amount

currencyrequired

Credit amount denominated in currency. Minimum of 0.01.

parent_id

objectIdrequired

The ID of the parent customer.

currency

string

Three-letter ISO currency code in uppercase. Defaults to the store's base currency.

credit_id

objectId

ID of the credit applied to the customer's account.

number

stringauto

Unique incremental number assigned automatically each time an account credit is created.

PUT/accounts:credits/:id

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/accounts:credits/{id}', {
  email: 'sheogorath@shiveringisles.com'
});

Response

{
  "parent_id": "621e53a6213eaf013d1fa6b2",
  "amount": 17,
  "reason": "refund",
  "currency": "USD",
  "date_created": "2022-07-08T20:27:40.199Z",
  "number": "100003",
  "date_updated": "2022-07-12T16:02:14.965Z",
  "id": "62c8933c5f4ffe00136039f2"
}

List all account credits

Return a list of customer account credits.

Arguments

expand

string

Expand link fields and child collections by using the expand argument.

For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fields

string

Returns only the specified fields in the result.

For example fields=name,slug would return only the fields name and slug in the response.

Supports nested object and array fields using dot-notation.

For example, items.product_id. The product id is always returned.

include

object

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limit

int

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

page

int

The page number of results to return given the specified or default limit.

search

string

A text search is performed using the search argument. Searchable fields are defined by the model.

For example, search=red would return records containing the word "red" anywhere in the defined text fields.

See searching for more details.

sort

string

Expression to sort results by using a format similar to a SQL sort statement.

For example, sort=name asc would return records sorted by name ascending.

See sorting for more details.

where

object

An object with criteria to filter the result.

For example, active=true would return records containing a field active with the value true.

It's also possible to use query operators, for example, $eq, $ne, $gt, and more.

See querying for more details.

GET/accounts:credits

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/accounts:credits/', {
});

Response

{
  "count": 3,
  "results": [
    {
      "parent_id": "621e53a6213eaf013d1fa6b2",
      "amount": 17,
      "reason": "refund",
      "currency": "USD",
      "date_created": "2022-07-08T20:27:40.199Z",
      "number": "100003",
      "date_updated": "2022-07-12T16:02:14.965Z",
      "id": "62c8933c5f4ffe00136039f2"
    },
    {
      "parent_id": "621506e39c5e9e013dac45a0",
      "amount": 15,
      "giftcard_id": "62166e0072c71f013d0b3216",
      "currency": "USD",
      "date_created": "2022-02-23T17:25:25.101Z",
      "number": "100002",
      "id": "62166e056050eb01329b8cce"
    },
    {
      "parent_id": "621506e39c5e9e013dac45a0",
      "amount": 10,
      "giftcard_id": "6206da29178ab8013d86c6aa",
      "currency": "USD",
      "date_created": "2022-02-23T17:24:28.605Z",
      "number": "100001",
      "id": "62166dcc6050eb01329a4359"
    }
  ],
  "page": 1
}

Delete an account credit

Delete a customer account credit permanently.

Arguments

id

objectId

Unique identifier of the account credit.

DELETE/accounts:credits/:id

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/accounts:credits/{id}', {
  id: '62c8933c5f4ffe00136039f2'
});

Response

{
      "parent_id": "621e53a6213eaf013d1fa6b2",
      "amount": 17,
      "reason": "refund",
      "currency": "USD",
      "date_created": "2022-07-08T20:27:40.199Z",
      "number": "100003",
      "date_updated": "2022-07-12T16:02:14.965Z",
      "id": "62c8933c5f4ffe00136039f2"
    },

← Back: Account cards Next: Invoices →