CRM CareCloud API Reference Purchases

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
customer_id	string	Id of the customer that made the purchase. You can search customers by plenty parameter in resource customers	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

CRM CareCloud REST API

Purchases

Available methods

Available methods with sub-resources

Actions

Get all purchases

Query string

Response

Example Request

Example response

Get a purchase

Path parameters

Response

Example Request

Example response

Return payment summary

Path parameters

Response

Example Request

Example response

Recommended best rewards

Request

Response

Example Request

Example response

Accept payment

Request

Response

Example request

Example response

Send purchase

Request

Response

Example request

Example response

Assign customer

Request

Response