Promotions

GoBiz allows a partner to create SKU-level promotions specific to any outlet. You can create a promotion, view a list of promotions for a specific outlet, and also delete or deactivate a promotion.

The methods available in Promotions are listed in the table given below.

Method	Endpoint	Description
POST	/integrations/promo/outlets/{outlet_id}/v1/food-promos	It is used to create promotions for a specific outlet.
GET	/integrations/promo/outlets/{outlet_id}/v1/food-promos	It is used to retrieve the list of promotions for a specific partner.
GET	/integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id}	It is used to get the detailed information about a specific promotion.
DELETE	/integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id}	It is used to delete a specific promotion.
PUT	/integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id}/deactivate	It is used to deactivate an active promotion.

Create Promotions

It helps you to create promotions for a specific outlet.

POST /integrations/promo/outlets/{outlet_id}/v1/food-promos

Sample Request

Sample Request

curl -X POST https://api.partner-sandbox.gobiz.co.id/integrations/promo/outlets/{outlet_id}/v1/food-promos \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: some-sample-request-id' \
  -H 'X-Idempotency-Key: 3f5751ac-4423-4f60-aeb9-aacb5e76e4d1' \
  -H 'Authorization: Bearer {access-token}' \
  -d $'
  {
    "promo_type": "sku_promo",
    "promo_detail": {
      "start_date": "2020-09-04",
      "end_date": "2020-09-07",
      "start_time" : "14:00:00",
      "end_time" : "16:00:00",
      "selling_price": 2500,
      "external_menu_id": "external_menu_id",
      "applicable_days" : ["sunday", "monday"]
    }
  }
  '

Path Parameter

Name	Description	Type	Required
outlet_id	ID of the outlet for which you want to create a promotion.	String	Required

Header Parameters

Name	Description	Type	Required
X-Request-ID	It is used to track the request. It is sent back on the response headers. If a request ID already exists as the x-request-id in the HTTP request header and fulfills the length requirements, then it is used. Otherwise, a new request ID is generated and the request is not rejected. Maximum Limit: 128 characters.	String	Optional
X-Idempotency-Key	A valid UUID that is used to identify whether the request is a new request or a retry request. Maximum Limit: 36 characters.	String(UUID)	Required

Request Parameters

JSON Attribute	Description	Type	Required
promo_type	Type of the promotion. Value: sku_promo	String	Required
promo_detail	Details of a promotion.	Object	Required

note

• You can select to define the discounted selling price or the discount percentage. If you want to define the selling price, you can use selling_price field. If you want to define the discount in percentage, you can use percentage_discount field.
• If start_date is same as current date, the promo is activated immediately.
• If start_date is greater than the current date, then the promo is activated from midnight of start_date.
• If Menu name or Item name is changed, then the promo disappears.
• SKU promo uses external_item_id as a reference, hence the promo will be applied for all the items with the same external_item_id.
• The final price must be between 10% (minimum) and 99% (maximum) of the original price.
• Current maximum duration of a promo is 62 days for Production environment, and 30 days for Sandbox environment.
• The end_date of promo should be greater than the start_date.
• start_date should be equal to or greater than the catalog update date.
• You can create a promotion that targets specific time. For example, you want to enable the promotion only on dinner time (18.00-21.00). You can use start_time and end_time field to define the time-range.
• Should you choose to use start_time and end_time, the promotion time must be between 1 hour (minimum) and 6 hours (maximum).
• You can create a promotion that targets specific days within a week. For example, you want to enable the promotion only on Monday and Thursday. You can use applicable_days field to define them.

Sample Response - 201 Success

Sample Response

{
  "success": true,
  "data": {
    "success": [
      {
        "id": "promotion_id",
        "external_menu_id": "external-menu-id",
        "errors": null
      }
    ],
    "failure": [
      {
        "id": null,
        "external_menu_id": "external-menu-id",
        "errors": "Item is not active"
      }
    ]
  }
}

Response Parameters - 201 Success

JSON Attribute	Description	Type
success	Status of the request. Value true indicates successful submission of the request.	Boolean
data	Details of the promotion including success and error cases.	Object
» success	Details of the promotion when request is successfully submitted.	Object
» failure	Details of the promotion when request fails.	Object

note

• To perform this operation, Direct Integration partner must be authenticated using go_auth_client_credentials(promo:food_promo:write).
• To perform this operation, Facilitator partner must be authenticated using go_auth_authorization_code(promo:food_promo:write).
• Possible error responses are 401, 404, 406, and 415. Please refer Error Glossary.

Get Promotions

This method allows you to retrieve the list of promotions for a specific outlet.

GET /integrations/promo/outlets/{outlet_id}/v1/food-promos

Sample Request

Sample Request

curl -X GET https://api.partner-sandbox.gobiz.co.id/integrations/promo/outlets/{outlet_id}/v1/food-promos \
  -H 'X-Request-ID: some-sample-request-id' \
  -H 'Authorization: Bearer {access-token}'

Path Parameter

Name	Description	Type	Required
outlet_id	ID of the outlet for which you want to view the list of promotions.	String	Required

Header Parameters

Name	Description	Type	Required
X-Request-ID	It is used to track the request. It is sent back on the response headers. If a request ID already exists as the x-request-id in the HTTP request header and fulfills the length requirements, then it is used. Otherwise, a new request ID is generated and the request is not rejected. Maximum Limit: 128 characters.	String	Optional

Query Parameters

Name	Description	Type	Required
limit	Number of promotions to be displayed per page. If zero or null value is passed, it uses the default value, which is 25.	Integer	Optional
page	The page number to display the promotions.	Integer	Optional

Sample Response - 200 Success

Sample Response

{
  "success": true,
  "data": {
    "promotions": [
      {
        "start_date": "2020-09-04",
        "end_date": "2020-09-04",
        "status": "created",
        "id": "96f614f6-745e-47f5-ad68-c0c8e9ba8dc8"
      }
    ],
    "total_count": 100,
    "limit": 10,
    "page": 2
  }
}

Response Parameters - 200 Success

JSON Attribute	Description	Type
success	Status of the request. Value true indicates successful submission of the request.	Boolean
data	Details of the promotions.	Object
» promotions	Array of the promotions object.	Object
» total_count	Total count of the promotions.	Integer
» limit	Number of the promotions per page.	Integer
» page	The page number displaying the promotions.	Integer

note

• To perform this operation, Direct Integration partner must be authenticated using go_auth_client_credentials(promo:food_promo:read).
• To perform this operation, Facilitator partner must be authenticated using go_auth_authorization_code(promo:food_promo:read).
• Possible error responses are 401, 404, 406, and 415. Please refer Error Glossary.

Get a Promotion Detail

By using this method, you can get the detailed information about a specific promotion.

GET /integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id}

Sample Request

curl -X GET https://api.partner-sandbox.gobiz.co.id/integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id} \
  -H 'X-Request-ID: some-sample-request-id' \
  -H 'Authorization: Bearer {access-token}'

Path Parameters

Name	Description	Type	Required
outlet_id	ID of the outlet for which you want to view the details of a promotion.	String	Required
promotion_id	ID of the promotion whose details you want to view.	String	Required

Header Parameter

Name	Description	Type	Required
X-Request-ID	It is used to track the request. It is sent back on the response headers. If a request ID already exists as the x-request-id in the HTTP request header and fulfills the length requirements, then it is used. Otherwise, a new request ID is generated and the request is not rejected. Maximum Limit: 128 characters.	String	Optional

Sample Response - 200 Success

Sample Response

{
  "success": true,
  "data": [
    {
      "id": "96f614f6-745e-47f5-ad68-c0c8e9ba8dc8",
      "start_date": "2020-09-04",
      "end_date": "2020-09-04",
      "start_time": "14:25:00",
      "end_time": "14:55:00",
      "status": "activated",
      "promo_type": "sku_promo",
      "details": {
        "menu_item": {
          "id": "45ba745f-745e-4568-ad68-c0c8e9ba8dc8",
          "external_menu_id": "external-menu-id",
          "name": "Kopi",
          "price": 4500,
          "discounted_price": 2500
        }
      }
    }
  ]
}

Response Parameters - 200 Success

JSON Attribute	Description	Type
success	Status of the request. Value true indicates successful submission of the request.	Boolean
data	Details of the promotions.	Object

note

• To perform this operation, Direct Integration partner must be authenticated using go_auth_client_credentials(promo:food_promo:write).
• To perform this operation, Facilitator partner must be authenticated using go_auth_authorization_code(promo:food_promo:write).
• Possible error responses are 401, 404, 406, and 415. Please refer Error Glossary.

Deactivate a Promotion

You can deactivate an active promotion for a specific outlet using this method.

PUT /integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id}/deactivate

Sample Request

curl -X PUT https://api.partner-sandbox.gobiz.co.id/integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id}/deactivate \
  -H 'X-Request-ID: some-sample-request-id' \
  -H 'Authorization: Bearer {access-token}'

Path Parameters

Name	Description	Type	Required
outlet_id	ID of the outlet for which you want to deactivate a promotion.	String	Required
promotion_id	ID of the promotion that you want to deactivate.	String	Required

Header Parameter -

Name	Description	Type	Required
X-Request-ID	It is used to track the request. It is sent back on the response headers. If a request id already exists as the x-request-id in the HTTP request header and fulfills the length requirements, then it is used. Otherwise, a new request id is generated and the request is not rejected. Maximum Limit: 128 characters.	String	Optional

Sample Response - 200 Success

{
  "success": true
}

Response Parameter - 200 Success

JSON Attribute	Description	Type
success	Status of the request. Value true indicates successful submission of the request.	Boolean

note

• To perform this operation, Direct Integration partner must be authenticated using go_auth_client_credentials(promo:food_promo:write).
• To perform this operation, Facilitator partner must be authenticated using go_auth_authorization_code(promo:food_promo:write).
• Possible error responses are 401, 404, 406, and 415. Please refer Error Glossary.

Delete a Promotion

By using this method, you can delete a promotion associated with a specific outlet. Only promotion with created state can be deleted. To deactivate currently active promo, you can use Promo Deactivation API.

DELETE /integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id}

Sample Request

curl -X DELETE https://api.partner-sandbox.gobiz.co.id/integrations/promo/outlets/{outlet_id}/v1/food-promos/{promotion_id} \
  -H 'X-Request-ID: some-sample-request-id' \
  -H 'Authorization: Bearer {access-token}'

Path Parameters

Name	Description	Type	Required
outlet_id	ID of the outlet for which you want to delete a promotion.	String	Required
promotion_id	ID of the promotion that you want to delete.	String	Required

Header Parameter

Name	Description	Type	Required
X-Request-ID	It is used to track the request. It is sent back on the response headers. If a request id already exists as the x-request-id in the HTTP request header and fulfills the length requirements, then it is used. Otherwise, a new request id is generated and the request is not rejected. Maximum Limit: 128 characters.	String	Optional

Sample Response - 200 Success

{
  "success": true
}

Response Parameter - 200 Success

JSON Attribute	Description	Type
success	Status of the request. Value true indicates successful submission of the request.	Boolean

note

• Active promotion can not be deleted.
• To perform this operation, Direct Integration partner must be authenticated using go_auth_client_credentials(promo:food_promo:write).
• To perform this operation, Facilitator partner must be authenticated using go_auth_authorization_code(promo:food_promo:write).