In this tutorial, you'll learn below mentioned product related operations in a contract.

Add or Update a product

Using the POST /contracts/{contract_id}/product_groups/{product_group_id}/products endpoint, you can add a product to a specific product group in a contract.

There are two ways of updating an existing product in a contract:

Using the PUT /contracts/{contract_id}/products/{product_id} endpoint, you can update an existing product in a contract without specifying the product group.
Using the PUT /contracts/{contract_id}/product_groups/{product_group_id}/products/{product_id} endpoint, you can update an existing product in a contract within a specified product group.

Currently, you can add a new product or update an existing product with the following attributes.

custom_id

📘
Note:
custom_id must be unique for each product in a contract.

counterparty_lock
description
name
price_1
price_2
quantity

📘
Note:
For the single_choice and multiple_choice types, the amount must be 0 or 1. When a product group has two or more single_choice products, only one product's quantity amount can be 1.

📘
Note:
If you send a PUT request with an empty request body {}, none of the attributes are required. The request will not update the specified product.

🚧
Note:
You can add only one type of discount: discount_percent or discount_amount. One of them should be null or 0. You can remove one or both from the request body.

Step 1. Obtain necessary information

To run the script described in this step, you’ll need the following data:

Headers
`x-oneflow-api-token`	You will only be able to run the script by using a valid API token. You can create an API token in the Oneflow web application. Find out more in the Authentication section.
`x-oneflow-user-email`	Your Oneflow user account email.
Path parameters
`CONTRACT_ID`	The unique ID of the contract where you want to update a product. You can find the contract ID using the contracts endpoint.
`PRODUCT_GROUP_ID`	The unique ID of the product group where you want to update a product.
`PRODUCT_ID`	The unique ID of the of the product that you want to update.
Body
`counterparty_lock`	Indicates if the counterparty can edit the product in the contract. The default value is `false`.
`description`	The description of the product.
`name`	The name of the product.
_private_ownerside
`custom_id`	A custom identifier you can use to address the products in a contract.
price_1	The price of the product.
price_2	The alternative price of the product, for example, the monthly payment fee.
`discount_percent`	The percentage discount off the base price.
base_amount
`amount`	The sum of the base price of the product, excluding the discount.
discount_amount
`amount`	The amount of the discount from the base price. This value must not be greater than the base price.
quantity
`amount`	The number of selected products.
`type`	One of the product quantity types (`multiple_choice, single_choice, quantity`).

Step 2. Run the code

Depending on the selected endpoint, replace the values of the parameters in the following commands with the actual data from your account and run it:

Add a product to a product group

curl --request POST \
     --url https://api.oneflow.com/v1/contracts/10015/product_groups/75861/products \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]' \
     --data '
{
    "_private_ownerside":{
        "custom_id": "Rose"
    },
    "counterparty_lock": false,
    "description": "Fresh Rose",
    "name": "Rose",
    "price_1":{
        "base_amount": {
            "amount": "500.00"
        },
        "discount_percent": "10.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "price_2":{
        "base_amount": {
            "amount": "400.00"
        },
        "discount_percent": "12.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "quantity":{
        "amount": 1,
        "type": "single_choice"
    }
}'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/product_groups/123456/products/122902813/products"

payload = {
    "_private_ownerside":{
        "custom_id": "Rose"
    },
    "counterparty_lock": false,
    "description": "Fresh Rose",
    "name": "Rose",
    "price_1":{
        "base_amount": {
            "amount": "500.00"
        },
        "discount_percent": "10.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "price_2":{
        "base_amount": {
            "amount": "400.00"
        },
        "discount_percent": "12.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "quantity":{
        "amount": 1,
      	"type": "single_choice"
    }
}
headers = {
    "Accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Update a product with no product group

curl --request PUT \
     --url https://api.oneflow.com/v1/contracts/10015/products/122902813 \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]' \
     --data '
{
    "_private_ownerside":{
        "custom_id": "Rose"
    },
    "counterparty_lock": false,
    "description": "Fresh Rose",
    "name": "Rose",
    "price_1":{
        "base_amount": {
            "amount": "500.00"
        },
        "discount_percent": "10.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "price_2":{
        "base_amount": {
            "amount": "400.00"
        },
        "discount_percent": "12.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "quantity":{
        "amount": 1,
        "type": "single_choice"
    }
}'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/products/122902813"

payload = {
    "_private_ownerside":{
        "custom_id": "Rose"
    },
    "counterparty_lock": false,
    "description": "Fresh Rose",
    "name": "Rose",
    "price_1":{
        "base_amount": {
            "amount": "500.00"
        },
        "discount_percent": "10.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "price_2":{
        "base_amount": {
            "amount": "400.00"
        },
        "discount_percent": "12.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "quantity":{
        "amount": 1,
      	"type": "single_choice"
    }
}
headers = {
    "Accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]",
    "Content-Type": "application/json"
}

response = requests.request("PUT", url, json=payload, headers=headers)

print(response.text)

Update a product within a product group

curl --request PUT \
     --url https://api.oneflow.com/v1/contracts/10015/product_groups/123456/products/122902813 \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]' \
     --data '
{
    "_private_ownerside":{
        "custom_id": "Rose"
    },
    "counterparty_lock": false,
    "description": "Fresh Rose",
    "name": "Rose",
    "price_1":{
        "base_amount": {
            "amount": "500.00"
        },
        "discount_percent": "10.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "price_2":{
        "base_amount": {
            "amount": "400.00"
        },
        "discount_percent": "12.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "quantity":{
        "amount": 1,
      	"type": "single_choice"
    }
}'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/product_groups/123456/products/122902813"

payload = {
    "_private_ownerside":{
        "custom_id": "Rose"
    },
    "counterparty_lock": false,
    "description": "Fresh Rose",
    "name": "Rose",
    "price_1":{
        "base_amount": {
            "amount": "500.00"
        },
        "discount_percent": "10.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "price_2":{
        "base_amount": {
            "amount": "400.00"
        },
        "discount_percent": "12.0",
        "discount_amount":{
            "amount": "0.0"
        }
    },
    "quantity":{
        "amount": 1,
      	"type": "single_choice"
    }
}
headers = {
    "Accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]",
    "Content-Type": "application/json"
}

response = requests.request("PUT", url, json=payload, headers=headers)

print(response.text)

Expected response

The response for the above endpoints will be as follows:

{
    "_private_ownerside": {
        "created_time": "2022-08-26T02:57:58+00:00",
        "custom_id": "Rose",
        "updated_time": "2022-08-30T06:03:20+00:00"
    },
    "counterparty_lock": false,
    "description": "Fresh Rose",
    "id": 122902813,
    "name": "Rose",
    "price_1": {
        "amount": {
            "amount": "450.00"
        },
        "base_amount": {
            "amount": "500.00"
        },
        "discount_amount": {
            "amount": "0.00"
        },
        "discount_percent": "10.000"
    },
    "price_2": {
        "amount": {
            "amount": "352.00"
        },
        "base_amount": {
            "amount": "400.00"
        },
        "discount_amount": {
            "amount": "0.00"
        },
        "discount_percent": "12.000"
    },
    "quantity": {
        "amount": 1,
        "type": "single_choice"
    }
}

Get a product or products

There are two ways to get a product in a contract:

Using the GET /contracts/{contract_id}/product_groups/{product_group_id}/products/{product_id} endpoint, you can get an existing product within a product group in a contract.
Using the GET /contracts/{contract_id}/products/{product_id} endpoint, you can get an existing product in a contract without specifying the product group.

Using the GET /contracts/{contract_id}/products endpoint, you can get all products in a contract.

Step 1. Obtain necessary information

To run the script described in this step, you’ll need the following data:

Headers
`x-oneflow-api-token`	You will only be able to run the script by using a valid API token. You can create an API token in the Oneflow web application. Find out more in the Authentication section.
`x-oneflow-user-email`	Your Oneflow user account email.
Path parameters
`CONTRACT_ID`	The unique ID of the contract which you want to get a product. You can find the contract ID using the contracts endpoint.
`PRODUCT_GROUP_ID`	The unique ID of the product group which you want to get a product.
`PRODUCT_ID`	The unique ID of the of the product which you want to get.

Step 2. Run the code

Depending on the selected endpoint, replace the values of the parameters in the following commands with the actual data from your account and run it:

Get a product in a product group

curl --request GET \
     --url https://api.oneflow.com/v1/contracts/10015/product_groups/75861/products/21934 \
     --header 'accept: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/product_groups/75861/products/21934"

headers = {
    "accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]"
}

response = requests.get(url, headers=headers)

print(response.text)

Get a product by ID

curl --request GET \
     --url https://api.oneflow.com/v1/contracts/10015/products/21934 \
     --header 'accept: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/products/21934"

headers = {
    "accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]"
}

response = requests.get(url, headers=headers)

print(response.text)

Expected response

The response for the get a product in a product group and get a product by ID endpoint will be as follows:

{
  "_private_ownerside": {
    "created_time": "2021-01-29T08:55:46+00:00",
    "custom_id": "c_shiny_shoes",
    "updated_time": "2021-01-29T08:55:46+00:00"
  },
  "counterparty_lock": false,
  "description": "shiny shoes for sunny saunters",
  "id": 21934,
  "name": "shoes",
  "price_1": {
    "amount": {
      "amount": "90.00"
    },
    "base_amount": {
      "amount": "100.00"
    },
    "discount_amount": {
      "amount": "0.00"
    },
    "discount_percent": "10.000"
  },
  "price_2": {
    "amount": {
      "amount": "0.00"
    },
    "base_amount": {
      "amount": "0.00"
    },
    "discount_amount": {
      "amount": "0.00"
    },
    "discount_percent": "0.000"
  },
  "quantity": {
    "amount": 1,
    "type": "multiple_choice"
  }
}

Get products in a contract

Replace the values of the parameters in the following command with the actual data from your account and run it:

curl --request GET \
     --url https://api.oneflow.com/v1/contracts/10015/products \
     --header 'accept: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/products"

headers = {
    "accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]"
}

response = requests.get(url, headers=headers)

print(response.text)

Expected response

The response for the above endpoint will be as follows:

{
  "count": 1,
  "data": [
    {
      "_private_ownerside": {
        "created_time": "2021-01-29T08:55:46+00:00",
        "custom_id": "c_shiny_shoes",
        "updated_time": "2021-01-29T08:55:46+00:00"
      },
      "counterparty_lock": false,
      "description": "shiny shoes for sunny saunters",
      "id": 135805,
      "name": "shoes",
      "price_1": {
        "amount": {
          "amount": "90.00"
        },
        "base_amount": {
          "amount": "100.00"
        },
        "discount_amount": {
          "amount": "0.00"
        },
        "discount_percent": "10.000"
      },
      "price_2": {
        "amount": {
          "amount": "0.00"
        },
        "base_amount": {
          "amount": "0.00"
        },
        "discount_amount": {
          "amount": "0.00"
        },
        "discount_percent": "0.000"
      },
      "quantity": {
        "amount": 1,
        "type": "multiple_choice"
      }
    }
  ]
}

Delete a product in a product group

Using the DELETE /contracts/{contract_id}/product_groups/{product_group_id}/products/{product_id} endpoint, you can delete an existing product within a product group in a contract.

Step 1. Obtain necessary information

To run the script described in this step, you’ll need the following data:

Headers
`x-oneflow-api-token`	You will only be able to run the script by using a valid API token. You can create an API token in the Oneflow web application. Find out more in the Authentication section.
`x-oneflow-user-email`	Your Oneflow user account email.
Path parameters
`CONTRACT_ID`	The unique ID of the contract where you want to delete a product. You can find the contract ID using the contracts endpoint.
`PRODUCT_GROUP_ID`	The unique ID of the product group where you want to delete a product.
`PRODUCT_ID`	The unique ID of the of the product that you want to delete.

Step 2. Run the code

Replace the values of the parameters in the following command with the actual data from your account and run it:

curl --request DELETE \
     --url https://api.oneflow.com/v1/contracts/10015/product_groups/75861/products/21934 \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/product_groups/75861/products/21934"

headers = {
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]"
}

response = requests.delete(url, headers=headers)

print(response.text)

Expected response

This operation will delete the specified product and display an empty body in the response.

Response codes

Response codes for the above mentioned endpoints as follows:

Status	Meaning	Description
200	OK	Returns the added product or updated product or specified product with products details or the product deleted successfully.
400	Bad Request	Invalid format or content of the request.
401	Unauthorized	The API token or the user email is invalid.
403	Forbidden	The request is not authorized by the server.
404	Not Found	A required entity is missing.
409	Conflict	A conflict occurred with the current state of the target resource