Purchases

There are the purchases tied to customer accounts stored in CRM CareCloud. The purchases are saved online when closing the bill or imported by the offline web service after the purchase. There are many parameters that specifies the purchase like bill items and its prices, date and time of the purchase, store, where purchase was made or loyalty card number. All this data are used for segmentation or voucher creation.

Available methods

All available methods for resource purchases.

HTTP method Endpoint Description
[badge-blue GET] /purchases Get information about a collection of purchases
[badge-blue GET ] /purchases/{purchase_id} Get information about a specific purchase

Available methods with sub-resources

All available methods for sub-resources of resource purchases.

HTTP method Endpoint Description
[badge-blue GET ] /purchases/{purchase_id}/purchase-items Collection of the purchase items
[badge-blue GET ] /purchases/{purchase_id}/vouchers Collection of vouchers
[badge-blue GET ] /purchases/{purchase_id}/points Collection of points

Actions

Action methods for resource purchases.

HTTP method Endpoint Description
[badge-blue GET] /purchases/{purchase_id}/actions/payment-summary Action method returns payment summary of the purchase. Shows credit, points and vouchers summary.
[badge-green POST] /purchases/actions/recommended-best-rewards Method returns all available rewards for POS installation. Rewards can be used later in send purchase process
[badge-green POST] /purchases/actions/accept-payment This method processes purchase closure from POS
[badge-green POST] /purchases/actions/send-purchase Method send the final closed bill to CareCloud from POS
[badge-green POST] /purchases/actions/assign-customer Method assigns a customer to existing purchase

Get all purchases

Get a list of purchases saved in CRM
[badge-blue GET] /purchases

Query string

Parameter name Type Description Mandatory (Yes/No)
count integer The number of records to return.
Default value is 100.
No
offset integer The number of records from a collection to skip.
Default value is 0.
No
sort_field string One of the query string parameters for sorting.
Response is sorted by the specified field.
No
sort_direction string Direction of sorting the response list.
Possible values are: ASC / DESC
No
store_id string The unique id for the store where purchase was made No
customer_id string The unique id for the customer No
type_id string Purchase type No
payment_time_from string Date and time from of the purchase payment (YYYY-MM-DD HH:MM:SS) No
payment_time_to string Date and time to of the purchase payment (YYYY-MM-DD HH:MM:SS) No
purchase_items_extension boolean If true, resource returns extended response with purchase items. If false, the resource won't be extended. If the parameter is not set, the default value is false No

Response

Status code: 200 OK
Output structure : object

Parameter name Type Description
purchases Purchase[] List of purchases
total_items integer Count of all found purchases

Example Request

GET https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases?count=1&purchase_items_extension=true&offset=99
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY2U6NGRmOzI1ZTcYTdhYmQ0OWVhZWJhYzE2OTI3NTQxMDY0Y2MxYjk3NTBhNGYxMTFmNzhhYTYwMTg1Mg==

Example response

HTTP/1.1 200 OK
Date: Tue, 27 Apr 2021 16:36:29 GMT
Content-Type: application/json; charset=utf-8

{
  "data": {
    "purchases": [
      {
        "purchase_id": "80c0e8d018748b2106387694bf",
        "customer_id": "8bc8ea4c1466859cbba26e522f",
        "store_id": "8fd73167342d06899c4c015320",
        "external_purchase_id": "208",
        "payment_time": "2012-11-14 21:16:51",
        "items_count": 2,
        "purchase_items": [
          {
            "purchase_item_id": "84b757641df03b1529c2c7f66c",
            "product_id": "89b3b24b405f461c63d8fcaa0c",
            "external_id": null,
            "purchase_item_type_id": "86e05affc7a7abefcd513ab400",
            "price": 1.99,
            "amount": null,
            "vat_rate": null,
            "additional_properties": [
              {
                "property_record_id": "note:84b757641df03b1529c2c7f66c",
                "property_id": "note",
                "property_name": "note",
                "property_value": null,
                "last_change": null
              },
              {
                "property_record_id": "transaction_discounts:84b757641df03b1529c2c7f66c",
                "property_id": "transaction_discounts",
                "property_name": "Discounts",
                "property_value": [],
                "last_change": null
              },
              {
                "property_record_id": "item_price:84b757641df03b1529c2c7f66c",
                "property_id": "item_price",
                "property_name": "Item price",
                "property_value": null,
                "last_change": null
              }
            ]
          },
          {
            "purchase_item_id": "82b4a764d9cd4b14780e011e33",
            "product_id": "83be813bf058ac655c1c7a2337",
            "external_id": null,
            "purchase_item_type_id": "86e05affc7a7abefcd513ab400",
            "price": 1.99,
            "amount": null,
            "vat_rate": null,
            "additional_properties": [
              {
                "property_record_id": "note:82b4a764d9cd4b14780e011e33",
                "property_id": "note",
                "property_name": "note",
                "property_value": null,
                "last_change": null
              },
              {
                "property_record_id": "transaction_discounts:82b4a764d9cd4b14780e011e33",
                "property_id": "transaction_discounts",
                "property_name": "Discount",
                "property_value": [],
                "last_change": null
              },
              {
                "property_record_id": "item_price:82b4a764d9cd4b14780e011e33",
                "property_id": "item_price",
                "property_name": "Item Price",
                "property_value": null,
                "last_change": null
              }
            ]
          }
        ],
        "type_id": "86e05affc7a7abefcd513ab400",
        "total_price": 18.96,
        "currency_id": "86e05affc7a7abefcd513ab400",
        "card_number": "2001990001884",
        "cashdesk_number": 2,
        "last_change": "2012-11-14 21:15:52.918601"
      }
    ],
    "total_items": 156919
  }
}

Response code: 200 (OK); Time: 623ms; Content length: 3457 bytes

Get a purchase

Get information about a specific purchase
[badge-blue GET] /purchases/{purchase_id}

Path parameters

Parameter name Type Description Mandatory (Yes/No)
purchase_id string The unique id for the purchase Yes

Response

Status code: 200 OK
Output structure : Purchase

Example Request

GET https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/8bc3btbb6f14765b3025cea06c
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY2U6NDU3NDJhMDAxNmEyZjctNDI3YWUwMTM0NmMyOWQxNmE4NzI1MWZlzZmMzcwNmI2MDJmDfN2Q2Mw==

Example response

HTTP/1.1 200 OK
Date: Tue, 20 Oct 2020 13:21:07 GMT
Content-Type: application/json; charset=utf-8

{
  "data": {
    "purchase_id": "8bc3bbb6f147465b025cea06c",
    "customer_id": "8bc8ea4c1466859cba26e522f",
    "store_id": "8fd73167342d06899c4c15320",
    "external_purchase_id": "274430",
    "payment_time": "2012-10-04 11:00:13",
    "items_count": 9,
    "purchase_items": null,
    "type_id": "86e05affc7a7abefcd51ab400",
    "total_price": 35.47,
    "currency_id": "86e05affc7a7abefcd53ab400",
    "card_number": "2001990001884",
    "cashdesk_number": 1,
    "last_change": "2012-10-04 10:54:07.994253"
  }
}


Return payment summary

Action method shows credit, point and voucher summary of purchase.
[badge-blue GET] /purchases/{purchase_id}/actions/payment-summary

Path parameters

Parameter name Type Description Mandatory (Yes/No)
purchase_id string The unique id of the purchase Yes

Response

Status code: 200 OK
Output structure : object

Parameter name Type Description
earned_points float Amount of earned points of the purchase.
used_credits float Amount of credits used to pay of the purchase
used_points float Amount of points used to pay of the purchase
used_points_total float Amount of points used to pay and used in vouchers of the purchase
used_vouchers Voucher[] List of used vouchers

Example Request

GET http://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/81c08d0187y48b2106387694bf/actions/payment-summary
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZfJwcmlzZV9pbnRlcmZhY2U6MGNjMMzYTQE1NDg1OTNiYzJiMjYxOTQxNGY1ZjhhNGMyOTJmNjEwMzI3ZmMwNWZiNzUxYzNhNw==

Example response

HTTP/1.1 200 OK
Date: Tue, 20 Apr 2021 09:28:39 GMT
Content-Type: application/json; charset=utf-8

{
  "data": {
    "earned_points": 376,
    "used_credits": 0,
    "used_points": 0,
    "used_points_total": 0,
    "used_vouchers": []
  }
}


Recommended best rewards

Method returns all available rewards for POS installation. The output contains list of all available and valid rewards. Each reward contains a parameter of maximum usage of rewards in a purchase. If amount equals zero, reward can not be applied. Rewards are allways connected to products through bill items.

[badge-green POST] /purchases/actions/recommended-best-rewards

Request

Parameter name Type Description Mandatory (Yes/No)
store_id string Id of store Yes
cashdesk_number string Number of the cashdesk in store Yes
card_number string A customer's card number Yes
reward_list_type string Type of the rewards
Possible values: F - full (all manual rewards available and valid for the specific POS)/ C -condensed (only manual rewards corresponding to items on the bill - maxCount not equals zero)/ A - all rewards list including automatic apply this is only for the DATA CUBE
Yes
bill Bill Structure of bill from POS Yes

Response

Status code: 200 OK
Output structure : object

Parameter name Type Description
recommended_best_rewards RecommendedReward[] List of the best rewards for POS
total_items integer Count of all found rewards

Example Request

POST https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/actions/recommended-best-rewards
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY26ZDxYmU2ZDkxyYjA4ZGMyZWQwMzkxYmFmOTkyMjhkNjJmN2IzMTk1MzM1YmYwMzhmMDQwMzBiZGQxMA==

{
  "store_id": "8fd73167342d06899c15320",
  "cashdesk_number" : "1",
  "reward_list_type" : "F",
  "bill": {
    "bill_id": "8fbea1c1eaa8edd35e7f278",
    "payment_time": "2016-06-30T15:5:49+02:00",
    "currency_id": "8bed991c6a470eaaffbf048",
    "total_price": "700",
    "bill_items": [{
      "plu_ids": [{
        "list_code": "GLOBAL",
        "code": "abc"
      }],
      "plu_name": "qwer",
      "category_plu_id": "8fbea1c1ea8edda5e67f27Q",
      "vat_rate": 4,
      "quantity": 2,
      "paid_amount": 6,
      "price": 4,
      "bill_item_id": "6fd73167342d6899c415320",
      "loyalty_off": true,
      "purchase_item_type_id": "89d3d433c86ec59fe51b18a"
    }]
  }

}

Example response

HTTP/1.1 200 OK
Date: Wed, 21 Apr 2021 08:54:24 GMT
Content-Type: application/json; charset=utf-8

{
  "data": {
    "recommended_best_rewards": [
      {
        "code": "PTV138",
        "name": "SVK_wine",
        "reward_priority": 9,
        "max_count": null,
        "description": "SVK_wine",
        "reward_properties": {
          "image": "",
          "valid_from": "00:00:00",
          "valid_to": "00:00:00"
        }
      }
    ],
    "total_items": 1
  }
}


Accept payment

The method processes bill closure requests. CareCloud returns information about discounts, applied vouchers, and points used for payment that change the bill's final price.

[badge-green POST] /purchases/actions/accept-payment

Request

Parameter name Type Description Mandatory (Yes/No)
store_id string Id of the store Yes
cashdesk_number integer A store cashdesk number Yes
card_number string A customer's card number No
payment_type string Method of the bill closure
Possible values: ā€œSā€-standard / ā€œDā€- use discount now
Yes
max_points string Amount of points to be redeemed No
max_credit string Amount of credits to be used No
benefit_codes string[] The bill closure will use present codes and recommend discounts No
bill Bill Structure of a bill from POS Yes

Response

Status code: 200 OK
Output structure : object

Parameter name Type Description
accepted_payment AcceptedPayment The structure contains values for applied rewards, vouchers, discounts, and other benefits

Example request

POST https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/actions/accept-payment
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY2U6lWZjMGU0NjFlZmQwZmY5YzU1ODI2NTg4NWM4NmM5MmQwYjRkMzJmYThmYzEzNTE2ZmY5NQ==

{
  "store_id": "8fd73167342d06899c4015320",
  "cashdesk_number": 1,
  "card_number": "2001990002294",
  "payment_type": "S",
  "max_points": "4",
  "max_credit": "7",
  "benefit_codes": [],
  "bill": {
    "bill_id": "89c91bbc4ddd440da11b86756",
    "bill_number": "54938",
    "payment_time": "2016-06-30T15:51:49+02:00",
    "created_by": "Rk",
    "currency_id": "8bed991c68a470eaaeffbf048",
    "total_price": "700",
    "utm": {
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "spring_sale"
    },
    "bill_items": [{
      "plu_ids": [{
        "list_code": "GLOBAL",
        "code": "NONONO"
      }],
      "plu_name": "GLOBAL",
      "category_plu_id": "8fbea1c1ea8eddca35e67f27Q",
      "vat_rate": 4,
      "quantity": 2,
      "paid_amount": 6,
      "price": 4,
      "bill_item_id": "8fbea1c1eaa8edda35e67f278",
      "loyalty_off": true,
      "purchase_item_type_id": "89d3d403c86e8c559fe51b18a",
      "customer_id": "86ae806b29ae109233bf2a5f5"
    }]
  }
}

Example response

HTTP/1.1 200 OK
Date: Mon, 26 Apr 2021 17:19:50 GMT
Content-Type: application/json; charset=utf-8

{
  "data": {
      "accepted_payment": {
        "recommended_discounts": [],
        "credit_points": 0,
        "price_of_credit_points": 0,
        "credit": 0,
        "benefit_codes": [],
        "credit_points_of_this_transaction": 0,
        "total_credit_points": 0,
        "total_credit": 960,
        "messages": []
      }
  }
}


Send purchase

The method sends the final closed bill to CareCloud. It returns info about success/failure in the response.

[badge-green POST] /purchases/actions/send-purchase

Request

Parameter name Type Description Mandatory (Yes/No)
store_id string Id of the store Yes
cashdesk_number integer Number of the cashdesk in the store Yes
card_number string Number of the customer's card No
bill FinalBill Structure of the final bill from POS Yes

Response

Status code: 201 Created
Output structure : object

Parameter name Type Description
purchase_id string Id of the created purchase

Example request

POST https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/actions/send-purchase
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhYMzcwNWMwMjBkNTQxYjgzNGYzNDkwMzIzYjlhODg1YmE2ZmI2YjMwNjYwMWY0MjVmOGI5NA==

{
  "store_id": "8fd73167342d0689c4c01z5320",
  "cashdesk_number": 1,
  "card_number": "6",
  "bill": {
    "fiscal": true,
    "purchase_type_id": "86e05affc7a7abefzcd513ab00",
    "canceled": false,
    "payment_type": "S",
    "payment_time": "2016-06-30T15:51:49+02:00",
    "currency_id": "8bed991c68a4707azaeffbf048",
    "total_price": "700",
    "payment_recap": {
      "credit_points": 7.0,
      "amount_for_credit": 4.2
    },
    "bill_id": 3424746665,
    "bill_number": "agkdoqjwe",
    "create_date_time": "2016-06-30T15:51:49+02:00",
    "bill_items": [{
      "plu_ids": [{
        "list_code": "GLOBAL",
        "code": "NONONO"
      }],
      "plu_name": "GLOBAL",
      "category_plu_id": "8fbea1c1eaa8edcza35e67fr27Q",
      "vat_rate": 4,
      "quantity": 2,
      "paid_amount": 6,
      "price": 43333,
      "bill_item_id": 4634,
      "loyalty_off": true,
      "purchase_item_type_id": "89d3d4303c86e8r559fe51b18a"
    }],
    "utm": {
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "spring_sale"
    }
  }
}

Example response

HTTP/1.1 201 Created
Date: Mon, 26 Apr 2021 11:18:48 GMT
Content-Type: application/json; charset=utf-8

{
  "data": {
    "purchase_id": "8da9ed69bc5fca59c55a308ce"
  }
}


Assign customer

The method assigns customer to the existing purchase. If customer could collect points, he is going to gain coresponding amount of points.

[badge-green POST] /purchases/actions/assign-customer

Request

Parameter name Type Description Mandatory (Yes/No)
store_id string Id of the store Yes
external_purchase_id string The unique external id of the purchase Yes
card_number string Number of the customer's card. Parameter is mandatory only if customer_id is not set. No
customer_id string The unique id of the customer. Parameter is mandatory only if card_number is not set. No

Response

Status code: 204 No Content
Output structure : object