Transaction API

1. Adding a Transaction

URL endpoint: https://stamps.co.id/api/v2/transactions/add

Allowed method: POST

Requires authentication: Yes

A. Request

You can add a new transaction on Stamps by calling the API with these parameters

Parameter	Required	Description
user	No	Email address / Member ID indicating customer. Leaving this empty creates an open transaction.
store	Yes	A number (id) indicating store where transaction is created
invoice_number	Yes	POS transaction number (must be unique daily)
total_value	Yes	A number indicating transaction’s grand total
number_of_people	Yes	An integer indicating the number of people involved in transaction
created	Yes	ISO 8601 date time format to indicate transaction’s created date (e.g. 2013-02-15T13:01:01+07)
sub_total	No	A number indicating transaction subtotal
discount	No	A number indicating transaction discount (in Rp.)
service_charge	No	A number indicating service charge (in Rp.)
tax	No	A number indicating transaction tax (in Rp.)
channel	No	Channel of a transaction. See channel mapping for more details.
type	No	The type of prepared transactions. See type mapping for more details.
items	No	List of item objects eligible_for_stamps is boolean value to determine whether the item should be included in Stamps Calculation. Defaults to true.
payments	No	List of payments object containing value, payment_method, and eligible_for_membership(optional). value is the amount of payment payment_method is the method used for payment eligible_for_membership whether this payment is used for member’s status/level changes. This field is optional. Default to true if not provided(can be configured later).
stamps	No	A number indicating custom stamps
require_email_notification	No	A boolean indicating send transaction to email if customer can retrieve email
employee_code	No	Employee code of sender employee
extra_data	No	Additional data for further processing

Here’s an example of how the API call might look like in JSON format:

{
   "user": "customer@stamps.co.id",
   "stamps": 10,
   "store": 32,
   "invoice_number": "my_invoice_number",
   "sub_total": 45000,
   "total_value": 50000,
   "number_of_people": 8,
   "tax": 5000,
   "channel": 1,
   "require_email_notification": false,
   "employee_code": "employee_code",
   "type": 2,
   "created": "2013-02-15T13:01:01+07",
   "extra_data": {
      "employee_name": "Stamps Employee",
      "order_number": "order_number"
   }
   "items": [
      {
         "product_name": "Cappucino",
         "quantity": 2,
         "subtotal": 10000,
         "stamps_subtotal": 4
      },
      {
         "product_name": "Iced Tea",
         "quantity": 4,
         "subtotal": 5000,
         "stamps_subtotal": 4,
         "eligible_for_stamps": false
      }
   ],
   "payments": [
      {
        "value": 30000,
        "payment_method": 10
      },
      {
        "value": 20000,
        "payment_method": 43,
        "eligible_for_membership": false
      }
   ]
}

Example of API call request using cURL (JSON). To avoid HTTP 100 Continue, please specify “Expect:” as a header.

$ curl -X POST -H "Content-Type: application/json" -H "Expect:" -H "Authorization: <token_type> <token>" https://stamps.co.id/api/v2/transactions/add -i -d '{ "created": "2017-03-30T07:01:01+07", "user": "customer@stamps.co.id", "store": 422, "number_of_people": 8, "tax":5000, "channel":1, "type":2, "invoice_number": "invoice_1", "total_value": 50000, "items": [{"product_name": "Cappucino", "quantity": 2, "subtotal": 10000}, {"product_name": "Iced Tea", "quantity": 4, "subtotal": 5000}]}, "payments": [{"value": 30000, "payment_method": 10}, {"value": 20000, "payment_method": 43, "eligible_for_membership": false}]'

B. Response

In response to this API call, Stamps will reply with the following data in JSON:

Variable	Description
transaction	Stamps transaction information that is successfully created. Contains id, value, number_of_people, discount and stamps_earned.
customer	Customer information after successful transaction. Contains id, mobile_phone, stamps_remaining, balance and status.
detail	Description of error (if any)
errors	Errors encountered when parsing data (if any)

Depending on the request, responses may return these status codes:

Code	Description
200	Everything worked as expected
400	Bad Request, usually missing a required parameter
401	Unauthorized, usually missing or wrong authentication token
403	Forbidden – You do not have permission for this request
405	HTTP method not allowed
500, 502, 503, 504	Something went wrong on Stamps’ server

Below are a few examples responses on successful API calls.

If transaction is successful(JSON):

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{
  "customer": {
    "status": "Blue",
    "balance": 150000,
    "mobile_phone": "+6281314811365",
    "id": 8120,
    "stamps_remaining": 401
  },
  "transaction": {
    "stamps_earned": 5,
    "id": 2374815,
    "value": 50000.0,
    "number_of_people": 8,
    "discount": 5000.0
  }
}

When some fields don’t validate (JSON):

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]


{"detail": "Your transaction cannot be completed due to the following error(s)", "errors": [{"subtotal": "This field is required."}, {"invoice_number": "Store does not exist"}]}

If HTTP is used instead of HTTPS:

HTTP/1.0 403 FORBIDDEN
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{"detail": "Please use https instead of http"}

If missing or wrong authentication token:

HTTP/1.0 403 FORBIDDEN
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{"detail": "Authentication credentials were not provided."}

C. Legacy Endpoint

Legacy endpoint’s documentation is available at Legacy transaction API

2. Adding a Transaction with Redemptions

URL endpoint: https://stamps.co.id/api/v2/transactions/add-with-redemptions

Allowed method: POST

Requires authentication: Yes

A. Request

You can add a new transaction with redemptions on Stamps by calling the API with these parameters

Parameter	Required	Description
user	No	Email address / Member ID indicating customer. Leaving this empty creates an open transaction.
store	Yes	A number (id) indicating store where transaction is created
invoice_number	Yes	POS transaction number (must be unique daily)
total_value	Yes	A number indicating transaction’s grand total
number_of_people	Yes	An integer indicating the number of people involved in transaction
created	Yes	ISO 8601 date time format to indicate transaction’s created date (e.g. 2013-02-15T13:01:01+07)
sub_total	No	A number indicating transaction subtotal
discount	No	A number indicating transaction discount (in Rp.)
service_charge	No	A number indicating service charge (in Rp.)
tax	No	A number indicating transaction tax (in Rp.)
channel	No	Channel of a transaction. See channel mapping for more details.
type	No	The type of prepared transactions. See type mapping for more details.
items	No	List of items containing product name, quantity, subtotal, stamps_subtotal (optional) & eligible_for_stamps (optional). price is the combined price of products (qty * unit price), stamps_subtotal is the combined stamps of products (qty * unit stamps), this field is optional. eligible_for_stamps is boolean value to determine whether the item should be included in Stamps Calculation. Defaults to true.
payments	No	List of payments object containing value, payment_method, and eligible_for_membership(optional). value is the amount of payment payment_method is the method used for payment eligible_for_membership whether this payment is used for member’s status/level changes. This field is optional. Default to true if not provided(can be configured later).
stamps	No	A number indicating custom stamps
require_email_notification	No	A boolean indicating send transaction to email if customer can retrieve email
employee_code	No	Employee code of sender employee
extra_data	No	Additional data for further processing
reward_redemptions	No	List of reward objects that want to be redeemed. Contains request_id, reward, and stamps (required if reward type is flexible reward). reward field can be filled with either reward ID (integer, i.e. 1) or reward code (string, i.e. REWARD1)
voucher_redemptions	No	List of voucher objects that want to be redeemed. Contains request_id and voucher_code
issue_voucher	No	Objects of data used to issue a voucher. Contains template_id and value (optional).

Here’s an example of how the API call might look like in JSON format:

{
   "user": "customer@stamps.co.id",
   "stamps": 10,
   "store": 32,
   "invoice_number": "my_invoice_number",
   "sub_total": 45000,
   "total_value": 50000,
   "number_of_people": 8,
   "tax": 5000,
   "channel": 1,
   "require_email_notification": false,
   "employee_code": "employee_code",
   "type": 2,
   "created": "2013-02-15T13:01:01+07",
   "extra_data": {
      "employee_name": "Stamps Employee",
      "order_number": "order_number"
   }
   "items": [
      {
         "product_name": "Cappucino",
         "quantity": 2,
         "subtotal": 10000,
         "stamps_subtotal": 4
      },
      {
         "product_name": "Iced Tea",
         "quantity": 4,
         "subtotal": 5000,
         "stamps_subtotal": 4,
         "eligible_for_stamps": false
      }
   ],
   "payments": [
      {
        "value": 30000,
        "payment_method": 10
      },
      {
        "value": 20000,
        "payment_method": 43,
        "eligible_for_membership": false
      }
   ],
   "reward_redemptions": [
      {
        "request_id": "request-id-1",
        "reward": 1
      },
      {
        "request_id": "request-id-1",
        "reward": "REWARDCODE"
      },
      {
        "request_id": "request-id-1",
        "reward": 1,
        "stamps": 10,
      }
      {
        "request_id": "request-id-1",
        "reward": "REWARDCODE",
        "stamps": 10,
      }
   ],
   "voucher_redemptions": [
      {
        "request_id": "request-id-1",
        "voucher_code": "VOUCHERCODE"
      }
   ],
   "issue_voucher": {
      "template_id": 1
      "value": 100000
   }
}

Example of API call request using cURL (JSON). To avoid HTTP 100 Continue, please specify “Expect:” as a header.

$ curl -X POST -H "Content-Type: application/json" -H "Expect:" -H "Authorization: <token_type> <token>" https://stamps.co.id/api/v2/transactions/add-with-redemptions -i -d '{ "created": "2017-03-30T07:01:01+07", "user": "customer@stamps.co.id", "store": 422, "number_of_people": 8, "tax":5000, "channel":1, "type":2, "invoice_number": "invoice_1", "total_value": 50000, "items": [{"product_name": "Cappucino", "quantity": 2, "subtotal": 10000}, {"product_name": "Iced Tea", "quantity": 4, "subtotal": 5000}]}, "payments": [{"value": 30000, "payment_method": 10}, {"value": 20000, "payment_method": 43, "eligible_for_membership": false}], "reward_redemptions": [ { "request_id": "request-id-1", "reward": 1 }, { "request_id": "request-id-1", "reward": "REWARDCODE" }, { "request_id": "request-id-1", "reward": 1, "stamps": 10, } { "request_id": "request-id-1", "reward": "REWARDCODE", "stamps": 10, } ], "voucher_redemptions": [ { "request_id": "request-id-1", "voucher_code": "VOUCHERCODE" } ]'

B. Response

In response to this API call, Stamps will reply with the following data in JSON:

Variable	Description
transaction	Stamps transaction information that is successfully created. Contains id, value, number_of_people, discount and stamps_earned.
membership	Contains membership data. Contains tags, status, status_text, stamps, balance, is_blocked, referral_code, start_date, and created
detail	Description of error (if any)
errors	Errors encountered when parsing data (if any)

Depending on the request, responses may return these status codes:

Code	Description
200	Everything worked as expected
400	Bad Request, usually missing a required parameter
401	Unauthorized, usually missing or wrong authentication token
403	Forbidden – You do not have permission for this request
405	HTTP method not allowed
500, 502, 503, 504	Something went wrong on Stamps’ server

Below are a few examples responses on successful API calls.

If transaction is successful(JSON):

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{
  "membership": {
    "tags": [],
    "status": 10,
    "status_text": "Blue",
    "stamps": 10,
    "balance": 20,
    "is_blocked": false,
    "referral_code": "asd",
    "start_date": "2020-01-01",
    "created": "2020-01-01",
  },
  "transaction": {
    "stamps_earned": 5,
    "id": 2374815,
    "value": 50000.0,
    "number_of_people": 8,
    "discount": 5000.0
  },
  "issued_voucher": {
    "id": 1,
    "code": "VC-ABC",
    "is_active": true,
    "quantity": 1,
    "value": 200,
    "notes": "",
    "start_date": "2022-03-28",
    "end_date": "2022-04-28",
    "constraint": {
        "channels": [1, 2, 3, 4],
    },
    "template": {
        "id": 1,
        "name": "March Surprise Voucher",
        "type": 1,
        "short_description": "Get 50% off on your next purchase",
        "picture_url": "foo.png",
        "landscape_picture_url": "foo_landscape.png",
        "merchant_id": 1,
        "merchant_code": "M-ABC",
        "extra_data": null,
    }
  }
}

When some fields don’t validate (JSON):

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]


{"detail": "Your transaction cannot be completed due to the following error(s)", "errors": [{"subtotal": "This field is required."}, {"invoice_number": "Store does not exist"}]}

If HTTP is used instead of HTTPS:

HTTP/1.0 403 FORBIDDEN
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{"detail": "Please use https instead of http"}

If missing or wrong authentication token:

HTTP/1.0 403 FORBIDDEN
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{"detail": "Authentication credentials were not provided."}

3. Canceling a Transaction

URL endpoint: https://stamps.co.id/api/v2/transactions/cancel

Allowed method: POST

Requires authentication: Yes

A. Request

You can cancel a transaction on Stamps by calling the API with these parameters

Parameter	Required	Description
invoice_number	Yes	The transaction’s invoice number
date	Yes	Date when the transaction is executed, in YYYY-MM-DD format

Here’s an example of how the API call might look like in JSON format:

{
   "invoice_number": "ABCD123",
   "date": "2021-02-01"
}

Example of API call request using cURL (JSON)

$ curl -X POST -H "Content-Type: application/json" -H "Authorization: <token_type> <token>" https://stamps.co.id/api/v2/transactions/cancel -i -d '{ "invoice_number": "ABCD123", "date": "2021-02-01" }'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON by default):

Variable	Description
transaction	Transaction information which is successfully canceled. Contains stamps_earned, id, and value
membership	Contains membership data. Contains tags, status, status_text, stamps, balance, is_blocked, referral_code, start_date, and created
errors	Errors encountered when canceling a transaction (if any)

C. Response Headers

Depending on the request, responses may return these status codes:

Code	Description
200	Everything worked as expected
400	Bad Request, usually missing a required parameter
401	Unauthorized, usually missing or wrong authentication token
403	Forbidden – You do not have permission for this request
404	Cannot find transaction of the requested transaction id
405	HTTP method not allowed
500, 502, 503, 504	Something went wrong on Stamps’ server

D. Example Response

Below are a few examples responses on successful API calls.

If transaction is successfully canceled:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
  "transaction": {
    "stamps_earned": 3,
    "id": 1,
    "value": 30000
    "status": "Canceled"
  },
  {
  "membership": {
    "tags": [],
    "status": 10,
    "status_text": "Blue",
    "stamps": 10,
    "balance": 20,
    "is_blocked": false,
    "referral_code": "asd",
    "start_date": "2020-01-01",
    "created": "2020-01-01",
  },
}

When some fields don’t validate:

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{"errors": {"info": "Transaction can't be canceled due to insufficient Stamps"}}

C. Legacy Endpoint

Legacy endpoint’s documentation is available at Legacy transaction API

4. Modify Transaction’s Value or Items

URL endpoint: https://stamps.co.id/api/v2/transactions/modify

Allowed method: POST

Requires authentication: Yes

Note: You may modify a transaction’s value or items. However, vouchers that were already issued from transaction bonuses or product bonuses are not automatically deactivated if the updated values no longer meet the bonus requirements.

A. Request

You can modify transaction’s value or items detail on stamps by calling the API with these parameters

Parameter	Required	Description
id	Yes	Transaction ID
total_value	Yes	Total value that want to deduct from a transaction
subtotal	Yes	Sub total value that want to deduct from a transaction
items	Yes	Items detail that want to deduct from a transaction

Here’s an example of how the API call might look like in JSON format:

{
   "id": 1,
   "total_value": -4000,
   "subtotal": -3000,
   "items": [
        {
            "product_name": "AQUA",
            "quantity": -1
        }
    ]
}

Example of API call request using cURL (JSON)

$ curl -X POST -H "Content-Type: application/json" -H "Authorization: <token_type> <token>" https://stamps.co.id/api/v2/transactions/modify -i -d '{ "id": 1, "total_value": -4000,"subtotal": -3000,"items": [{"product_name": "AQUA","quantity": -1}]'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON by default):

Variable	Description
transaction	Transaction information which is successfully modified. Contains stamps_earned, id, and value
customer	Customer information after successful redemption. Contains id, status, and stamps_remaining.
errors	Errors encountered when canceling a transaction (if any)

C. Response Headers

Depending on the request, responses may return these status codes:

Code	Description
200	Everything worked as expected
400	Bad Request, usually missing a required parameter
401	Unauthorized, usually missing or wrong authentication token
403	Forbidden – You do not have permission for this request
404	Cannot find transaction of the requested transaction id
405	HTTP method not allowed
500, 502, 503, 504	Something went wrong on Stamps’ server

D. Example Response

Below are a few examples responses on successful API calls.

If transaction is successfully canceled:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
  "transaction": {
    "id": 1,
    "value": 30000,
    "stamps_earned": 3,
    "number_of_people": 1
  },
  "customer": {
    "id": 5,
    "mobile_phone":null,
    "stamps_remaining": 62,
    "status": "Blue",
    "balance":0
  }
}

When some fields don’t validate:

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{"detail":"product_name: Product does not exists","error_message":"product_name: Product does not exists","error_code":"product_not_found","errors":{"product_name":"Product does not exists"}}

5. Getting Transaction Detail

URL endpoint: https://stamps.co.id/api/transactions/details

Allowed method: GET

Requires authentication: Yes

A. Request

You can get transaction’s detail data through this API.

Parameter	Required	Description
transaction_id	Yes	Transaction ID

Example of API call request using cURL

$ curl -H 'Authorization: <token_type> <token>' 'https://stamps.co.id/api/transactions/details?merchant=123&transaction_id=345'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
transaction	An object containing transaction information after successful request.

C. Example Response

On successful balance update:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: GET
  [Redacted Header]

  {
    "transaction": {
        "created": 1619734844,
        "discount": null,
        "items": [{
              "id": 1,
              "name": "Cafe Latte",
              "quantity": 1.0,
          },
          {
              "id": 2,
              "name": "Fried Rice",
              "quantity": 1.0,
          }
        ],
        "notes": "",
        "service_charge": null,
        "stamps": 150,
        "status": "Created",
        "store": {
            "display_name": "My Favorite Store",
            "id": 1,
            "name": "Fav Store"
        },
        "subtotal": null,
        "tax": null,
        "type": null,
        "value": 1500000.0,
        "payments": [{
            "id": 1,
            "value": 1500000.0,
            "eligible_for_stamps": 150,
            "payment_method_code": ABC
        }]
    }
}

6. Preview Transaction Earnings

URL endpoint: https://stamps.co.id/api/v2/transactions/preview-earnings

Allowed method: GET

Requires authentication: Yes

A. Request

You can preview transaction’s earning data before creating a transaction through this API.

Parameter	Required	Description
user	No	Email address / Member ID indicating customer. Leaving this empty creates an open transaction.
store	Yes	A number (id) indicating store where transaction is created
total_value	Yes	A number indicating transaction’s grand total
sub_total	No	A number indicating transaction subtotal
discount	No	A number indicating transaction discount (in Rp.)
service_charge	No	A number indicating service charge (in Rp.)
tax	No	A number indicating transaction tax (in Rp.)
channel	No	Channel of a transaction. See channel mapping for more details.
type	No	The type of prepared transactions. See type mapping for more details.
items	No	List of items containing product name, quantity, subtotal, stamps_subtotal (optional) & eligible_for_stamps. price is the combined price of products (qty * unit price), stamps_subtotal is the combined stamps of products (qty * unit stamps), this field is optional. eligible_for_stamps is boolean value to determine whether the item should be included in Stamps Calculation. Defaults to true.
payments	No	List of payments object containing value, payment_method, and eligible_for_membership(optional). value is the amount of payment payment_method is the method used for payment eligible_for_membership whether this payment is used for member’s status/level changes. This field is optional. Default to true if not provided(can be configured later).

Example of API call request using cURL (JSON)

$ curl -X POST -H "Content-Type: application/json" -H "Expect:" -H "Authorization: <token_type> <token>" https://stamps.co.id/api/v2/transactions/preview-earnings -i -d '{ "user": "customer@stamps.co.id", "store": 422, "tax":5000, "channel":1, "type":2, "total_value": 50000, "items": [{"product_name": "Cappucino", "quantity": 2, "subtotal": 10000}, {"product_name": "Iced Tea", "quantity": 4, "subtotal": 5000}]}, "payments": [{"value": 30000, "payment_method": 10}, {"value": 20000, "payment_method": 43, "eligible_for_membership": false}]'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
stamps	The amount of stamps to be received after completing the transaction.

C. Example Response

On successful balance update:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: GET
  [Redacted Header]

{
  "stamps": 10
}

7. List User Transaction

URL endpoint: https://stamps.co.id/api/transactions/by-user

Allowed method: GET

Requires authentication: Yes

A. Request

You can query latest user transaction’s list through this API.

Parameter	Required	Description
user	Yes	A string indicating customer’s email, Member ID, mobile number or primary key ID
last_transaction_id	No	An integer indicating customer transaction_id, will return transactions with less than given value
merchant_id	No	An array of merchant IDs to filter, fill with [0] to get all merchant in same group
channel	No	An integer array of transaction channels to filter. See channel mapping for more details.
start_date	No	Start of transaction created date to filter in YYYY-MM-DD format
end_date	No	End of transaction created date to filter in YYYY-MM-DD format

Example of API call request using cURL (JSON)

$ curl -H 'Authorization: <token_type> <token>' 'https://stamps.co.id/api/transactions/by-user?user=123&merchant_id=2&merchant_id=3&channel=2&channel=4&end_date=2022-09-12'

B. Response

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
transactions	list of user transactions contains, id, value, stamps_earned, number_of_people, discount, subtotal, invoice_number, created, merchant, status, and store
has_next	Boolean value indicating whether any older transaction exists.

C. Example Response

On successful get Transactions:

  HTTP/1.0 200 OK
  Vary: Accept
  Content-Type: application/json
  Allow: GET
    [Redacted Header]

  {
  "transactions": [
    {
      "id": 20,
      "value": 200000.0,
      "stamps_earned": 1,
      "number_of_people": null,
      "discount": null,
      "subtotal": null,
      "invoice_number": "0020014795:1:001",
      "created": 1661075448,
      "merchant": "Merchant Test",
      "merchant_id": 2,
      "status": 1,
      "meta": {
        "channel": 2,
        "channel_text": "POS"
      },
      "store": {
        "name": "0020014795",
        "display_name": "TEST STORE"
      }
    },
    {
      "id": 15,
      "value": 10000.0,
      "stamps_earned": 20,
      "number_of_people": null,
      "discount": null,
      "subtotal": 102.0,
      "invoice_number": "0020014795:1:002",
      "created": 1661075448,
      "merchant": "Merchant Test",
      "status": 2,
      "merchant_id": 3,
      "meta": {
        "channel": 2,
        "channel_text": "POS"
      },
      "store": {
        "name": "0020014795",
        "display_name": "TEST STORE"
      }
    }
  ],
  "has_next": true
}

8. Add or Update Transaction

URL endpoint: https://stamps.co.id/api/v2/transactions/add-or-update

Allowed method: POST

Requires authentication: Yes

A. Request

You can use this API to add a transaction or complete a transaction items details later after adding a transaction previously.

The payload for adding is identical to Adding a Transaction API.

The payload for updating a transaction has fewer required fields and items field is required, but otherwise compatible with Adding a Transaciton API payload:

Parameter	Required	Description
store	Yes	A number (id) indicating store where transaction is created
invoice_number	Yes	POS transaction number (must be unique daily)
items	Yes	List of item objects, but the subtotal/price is required, and must match original transaction value

So it is possible to use Adding a Transaction API payload format for both the purpose of adding and updating transaction.

Here’s an example of how the API call might look like in JSON format:

{
   "store": 32,
   "invoice_number": "my_invoice_number",
   "items": [
      {
         "product_name": "Cappucino",
         "quantity": 2,
         "subtotal": 10000,
         "stamps_subtotal": 4
      },
      {
         "product_name": "Iced Tea",
         "quantity": 4,
         "subtotal": 5000,
         "stamps_subtotal": 4,
         "eligible_for_stamps": false
      }
   ]
}

Example of API call request using cURL (JSON). To avoid HTTP 100 Continue, please specify “Expect:” as a header.

$ curl -X POST -H "Content-Type: application/json" -H "Expect:" -H "Authorization: <token_type> <token>" https://stamps.co.id/api/v2/transactions/add-or-update -i -d '{ "store": 422, "invoice_number": "invoice_1", "items": [{"product_name": "Cappucino", "quantity": 2, "subtotal": 10000}, {"product_name": "Iced Tea", "quantity": 4, "subtotal": 5000}] }'

B. Response

In response to this API call, Stamps will reply with the following data in JSON:

Variable	Description
transaction	Stamps transaction information that is successfully created. Contains id, value, number_of_people, discount and stamps_earned.
customer	Customer information after successful transaction. Contains id, mobile_phone, stamps_remaining, balance and status.
detail	Description of error (if any)
errors	Errors encountered when parsing data (if any)

Depending on the request, responses may return these status codes:

Code	Description
200	Everything worked as expected
400	Bad Request, usually missing a required parameter
401	Unauthorized, usually missing or wrong authentication token
403	Forbidden – You do not have permission for this request
405	HTTP method not allowed
500, 502, 503, 504	Something went wrong on Stamps’ server

Below are a few examples responses on successful API calls.

If transaction is successful:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{
  "customer": {
    "status": "Blue",
    "balance": 150000,
    "mobile_phone": "+6281314811365",
    "id": 8120,
    "stamps_remaining": 401
  },
  "transaction": {
    "stamps_earned": 5,
    "id": 2374815,
    "value": 50000.0,
    "number_of_people": 8,
    "discount": 5000.0
  }
}

When some fields don’t validate:

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
  "detail": "Your transaction cannot be completed due to the following error(s)",
  "errors": [
    {
      "invoice_number": "This Transaction's detail is already complete."
    }
  ]
}

If provided items price does not sum up to original transaction value:

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
 [Redacted Header]

{
  "error_code": "invalid_total_item_price",
  "detail": "Total item price need to equal transaction value"
}

Miscellaneous

Channel Mapping

Code	Description
1	Mobile App
2	POS
3	Kiosk
4	Web
5	Android
6	iOS
7	Call Center
8	GrabFood
9	GoFood

Type Mapping

Code	Description
1	Delivery
2	Dine-in
3	Take out
4	E-Commerce
5	Pickup

Status Mapping

Code	Description
1	New
2	Canceled
3	Open

Item Object

Parameter	Required	Description
product_name	Yes	Product name
quantity	Yes	Item quantity
subtotal/price	No	Combined price of products (qty * unit price)
stamps_subtotal	No	Combined stamps of products (qty * unit stamps)
eligible_for_stamps	No	Boolean value to determine whether the item should be included in Stamps Calculation. Defaults to true
extra_data	No	Additional data for further processing