Difference between revisions of "API Customer Credit"

From Spiffy Stores Knowledge Base

Line 204: Line 204:
 
==== Optional Parameters ====
 
==== Optional Parameters ====
  
{| class="wikitable" style="width: 100%"
+
{| class="reference"
|style="width: 30%"|fields
+
!fields
 
|A comma-separated list of fields to return in the response.
 
|A comma-separated list of fields to return in the response.
 
|}
 
|}

Revision as of 15:54, 6 June 2018

The Spiffy Stores API Customer Credit object represents a credit transaction that has been applied to a customer's account. Credits can be added to a customer's account when goods are returned or they may be used as a form of loyalty bonus.

Credits in a customer's account may then be used as payment or partial payment against future orders.

Customer Credit Properties

id { "id" : 123456789 }

A unique numeric identifier for the customer credit. This ID is only used with the API interface.

amount { "amount" : 54.53 }

The value of the customer credit. Positive amounts record an increase to the total credit assigned to the customer's account. A negative amount represents the amount of credit that has been posted against an order.

description { "description" : "Goods returned from Order #12345" }

The description provides reference information on why the credit was issued or redeemed.

customer { "customer" : {
  "id": 6,
  "title": "Mr",
  "first_name": "Frodo",
  "last_name": "Baggins",
  "name": "Mr Frodo Baggins",
  "email": "frodo@theshire.com",
  "accepts_marketing": true,
  "created_at": "2010-06-15T13:15:50Z",
  "updated_at": "2015-02-23T03:02:51Z",
  "note": "This customer has an interest in rings.",
  "orders_count": 512,
  "state": "enabled",
  "total_spent": "11230.63",
  "sign_in_count": 261,
  "current_sign_in_at": "2015-02-23T03:02:51Z",
  "current_sign_in_ip": "192.168.10.164",
  "last_sign_in_at": "2015-02-19T05:58:54Z",
  "last_sign_in_ip": "192.168.10.164",
  "wholesale": false,
  "credit": "0.0",
  "tags": "friend,ring_bearer,brave,hobbit"
} }

Returns an object containing information about the customer.

Customer objects contain the following fields:

  • id - A unique numeric identifier for the customer
  • title - The customer's title
  • first_name - The customer's first name
  • last_name - The customer's last name
  • name - The customer's full name, including title
  • email - The customer's email address
  • accepts_marketing - Acceptance of marketing emails
  • created_at - The date and time when the account was created
  • updated_at - The date and time when the account was updated
  • note - Additional information about the customer
  • orders_count - The number of orders placed by the customer
  • state - The current state of the customer's account
    Valid states are:
    • enabled
    • disabled
    • invited
    • declined
  • total_spent - The total amount spent by the customer
  • sign_in_count - The number of successful sign ins
  • current_sign_in_at - The time of the current sign in
  • current_sign_in_ip - The IP address of current sign in
  • last_sign_in_at - The time of the last sign in
  • last_sign_in_ip - The IP address of the last sign in
  • wholesale - Customer has access to wholesale prices
  • credit - Amount of credit in customer's account
  • tags - Tags associated with customer
order { "order" : { Order details… } }

Returns an object containing information about the order. The customer credit has an associated order only when a credit is being posted against a specific order.
More detailed information about the order can be found at API Order.

created_at { "created_at" : "2015-10-24T18:26:31Z" }

The date and time when the customer credit was created. The timestamp is in ISO 8601 format.

updated_at { "updated_at" : "2016-01-16T05:50:56Z" }

The date and time when the customer credit was last updated. The timestamp is in ISO 8601 format.

Endpoints

GET /api/customer_credits.json

Return a list of customer credits. Use the optional parameters to return specific customer credits.

Optional Parameters

limit Number of results returned. The default is 30, with a maximum of 50 in a single request.
page The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
ids A comma-separated list of order ids.
since_id Limit the results to only include objects which have an id greater than the given value.
created_at_min Return only the customer credits created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the customer credits created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the customer credits updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the customer credits updated before the given date and time. Use the format "2014-12-31 12:00".
customer_id Return all the customer credits belonging to the specified customer.
fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/customer_credits.json

HTTP/1.1 200 OK

{
  "customer_credits": [
    {
      "id": 3456,
      "amount": 5.0,
      "description": "Signup Bonus",
      "created_at": "2015-07-25T13:10:30Z",
      "updated_at": "2015-07-25T13:10:30Z",
      "customer":
        {
          "id": 6,
          "title": "Mr",
          "first_name": "Important",
          "last_name": "Customer",
          "name": "Mr Important Customer",
          "email": "customer@customer.domain.com",
          "accepts_marketing": true,
          "created_at": "2010-06-15T13:15:50Z",
          "note": "Here is some sample text.",
          "orders_count": 512,
          "state": "enabled",
          "total_spent": "11230.63",
          "updated_at": "2015-02-23T03:02:51Z",
          "sign_in_count": 261,
          "current_sign_in_at": "2015-02-23T03:02:51Z",
          "current_sign_in_ip": "192.168.10.164",
          "last_sign_in_at": "2015-02-19T05:58:54Z",
          "last_sign_in_ip": "192.168.10.164",
          "wholesale": true,
          "credit": "100.0",
          "tags":"friend,wholesaler"
        },
      "order": null
    }, ...
  ]
}

Examples using filters

GET /api/customer_credits.json?limit=10

GET /api/customer_credits.json?customer_id=2322

GET /api/customer_credits/count.json

Return a count of customer credits.

Optional Parameters

since_id Limit the results to only include objects which have an id greater than the given value.
created_at_min Return only the customer credits created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the customer credits created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the customer credits updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the customer credits updated before the given date and time. Use the format "2014-12-31 12:00".
customer_id Return all the customer credits belonging to the specified customer.

Example Request and Response

GET /api/customer_credits/count.json

HTTP/1.1 200 OK

{
  "count": 123
}

Examples using filters

GET /api/customer_credits/count.json?customer_id=2322

GET /api/customer_credits/CUSTOMER_CREDIT_ID.json

Return a single customer credit.

Optional Parameters

fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/customer_credits/16789.json

HTTP/1.1 200 OK

{
  "customer_credit":
    {
      "id": 16789,
      "created_at": "2015-02-27T18:08:33Z",
      "updated_at": "2015-02-27T18:08:33Z",
      "amount": -105.0,
      "description": "Payment for order #1234",
      ...
    }
}

POST /api/customer_credits.json

Create a new customer credit.

Example Request and Response

POST /api/custmer_credits.json

{
  "customer_credit": {
    "amount": 11.11,
    "description": "Signup bonus",
    "customer_id": 42
  }
}

HTTP/1.1 201 Created




Further Reference