Developer Documentation
IntegrationsHelp CenterSign in

Product

Suggest Edits

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

  1. Add or Update a product
  2. Get a product or products
  3. Delete a product

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:

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}/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:

StatusMeaningDescription
200OKReturns the added product or updated product or specified product with products details or the product deleted successfully.
400Bad RequestInvalid format or content of the request.
401UnauthorizedThe API token or the user email is invalid.
403ForbiddenThe request is not authorized by the server.
404Not FoundA required entity is missing.
409ConflictA conflict occurred with the current state of the target resource

Updated over 1 year ago