Products

Products are models that represent the Products and Subscriptions that you sell to your customers. They are used to create and manage subscriptions, and to create and manage invoices. You can setup metered billing, leveled billing, trial periods and more.

The Products Model

The Product model is used to create and manage products and subscriptions. It is used to create and manage invoices. You can setup metered billing, leveled billing, trial periods and more.

Properties

Name
id
Type
string
Description
Unique identifier for the conversation.
Name
organizationId
Type
string
Description
Unique identifier for the organization.
Name
productName
Type
string
Description
Name for the product (e.g. "Monthly Subscription", "Yearly Subscription", "Support", "Premium Support", etc.)
Name
amount
Type
float
Description
Amount for the product (e.g. 10.00, 20.00, 30.00, etc.)
Name
isOneTime
Type
boolean
Description
Is the product a one-time payment?
Name
expires
Type
boolean
Description
Does the product expire?
Name
cycles
Type
integer
Description
Number of cycles for the product (e.g. 1, 2, 3, etc.)
Name
cyclePeriod
Type
string
Description
Cycle period for the product (e.g. "month", "year", etc.)
Name
trialEnabled
Type
boolean
Description
Is the trial enabled for the product?
Name
trialAmount
Type
float
Description
Amount for the trial (e.g. 10.00, 20.00, 30.00, etc.)
Name
trialCycle
Type
integer
Description
Number of cycles for the trial (e.g. 1, 2, 3, etc.)
Name
trialCyclePeriod
Type
string
Description
Cycle period for the trial (e.g. "month", "year", etc.)
Name
createdAt
Type
datetime
Description
Date and time when the Product was created.
Name
updatedAt
Type
datetime
Description
Date and time when the Product was last updated.

GET/products/get/:organizationId

Get All Products

Get Products setup within BlueHill for your organization.

Required attributes

Request

GET

/products/get/:organizationId

curl --location --request GET 'https://api.bluehillpayments.io/products/get/{{organizationId}}'

Response

{
  "data": {
      "productGroup": [
          {
              "activeSubscriptions": 1,
              "averageValue": 40.0,
              "billingCycle": "Monthly",
              "createdAt": "2022-09-21 23:19:10",
              "id": "0C32EE233E3E431487C36D6ACFA1FDC3",
              "name": "Emails",
              "organizationId": "{{organizationId}}",
              "price": null,
              "pricing": {
                  "0D9CA55315B34D90A384F0D22B765B55": [
                      {
                          "billingCycle": "Monthly",
                          "createdAt": "2022-09-22 00:03:50",
                          "endDate": null,
                          "groupName": "Emails",
                          "id": "4B8035E4616746CF80BFD7D85F041305",
                          "levelName": "Level 6",
                          "lower": 5000.0,
                          "organizationId": "{{organizationId}}",
                          "price": 120.0,
                          "pricingId": "0D9CA55315B34D90A384F0D22B765B55",
                          "productGroupId": "0C32EE233E3E431487C36D6ACFA1FDC3",
                          "skewName": "2022 Pricing",
                          "startDate": null,
                          "updateAt": "2022-09-22 00:03:50",
                          "upper": 99999.0,
                          "variable": "emails"
                      },
                      ...
                  ]
              },
              "productGroupId": "FDA050CF22DE4A8CB6376A42D1F052DB",
              "productType": null,
              "tiers": [
                  {
                      "billingCycle": "Monthly",
                      "createdAt": "2022-09-22 00:03:50",
                      "endDate": null,
                      "groupName": "Emails",
                      "id": "4B8035E4616746CF80BFD7D85F041305",
                      "levelName": "Level 6",
                      "lower": 5000.0,
                      "organizationId": "{{organizationId}}",
                      "price": 120.0,
                      "pricingId": "0D9CA55315B34D90A384F0D22B765B55",
                      "productGroupId": "0C32EE233E3E431487C36D6ACFA1FDC3",
                      "skewName": "2022 Pricing",
                      "startDate": null,
                      "updateAt": "2022-09-22 00:03:50",
                      "upper": 99999.0,
                      "variable": "emails"
                  },
                  ...
              ],
              "totalBillables": 59,
              "totalRevenue": 40.0,
              "updateAt": "2022-09-21 23:19:10",
              "variable": "emails"
          },
          ...
      ]
  },
  "status": "success"
}

GET/products/get/:organizationId/:customerId

Get Available for Customer

Get products available for a customer based on their usage data.

Required attributes

Request

GET

/products/get/:organizationId/:customerId

curl --location --request GET 'https://api.bluehillpayments.io/products/get/37E1A66F6C464712B169251195C7F721/52204E2AD33746AD91F63B4AD3927F4A'

Response

{
  "data": {
      "customer": {
          "company": "Kids' Ark International Inc",
          "createdAt": "2023-01-13 18:26:44",
          "customerIds": null,
          "email": null,
          "fee": 5.0,
          "firstName": null,
          "id": "52204E2AD33746AD91F63B4AD3927F4A",
          "lastName": null,
          "notes": "",
          "organizationId": "37E1A66F6C464712B169251195C7F721",
          "phoneNumber": null,
          "state": "FL",
          "street": "3937 Cheverley Drive East",
          "town": "Lakeland",
          "uniqueHash": "AD00B88FB8654A6C8354A888F0D6BFB6",
          "updateAt": "2023-01-16 22:03:30",
          "zipCode": "33813"
      },
      "skews": [
          {
              "billingCycle": "One-Time",
              "createdAt": "2023-01-03 03:37:44",
              "endDate": null,
              "groupName": "DV Evolve Setup Fee",
              "id": "0AE8F2DBA0F4404A879D56E067C380FE",
              "levelName": "ALL",
              "lower": 0.0,
              "organizationId": "37E1A66F6C464712B169251195C7F721",
              "price": 49.0,
              "pricingId": "E0CF6B8C4E674B40AF5CF450A0B5A73F",
              "productGroupId": "D4F6D687C42B4492B0EA146B7C350570",
              "skewName": "2022 Pricing",
              "startDate": null,
              "updateAt": "2023-01-03 03:37:44",
              "upper": 3000000.0,
              "variable": "Constituents"
          },
          ...
      ]
  },
  "status": "success"
}

POST/products/create

Create Product

This endpoint allows you to retrieve a transaction by its unique identifier.

Request

POST

/products/create

  curl --location --request GET 'https://api.bluehillpayments.io/levels/get/EC8CD046740E43298BB1636DB0923A91' \
  --header 'Content-Type: application/json' \
  --data-raw ''

Response

{
  "data": {
      "createdAt": "2022-10-04 20:12:50",
      "customerId": "EC8CD046740E43298BB1636DB0923A91",
      "id": "4CFB21D282F14A8BB64A7A1B51EB7464",
      "levelProperties": {
          "constituents": "2800",
          "hasTakenReference": "true",
          "supportHours": "12",
          "text2Give": "1"
      },
      "organizationId": "{{organizationId}}",
      "updateAt": "2022-11-16 17:51:26"
  },
  "status": "success"
}

POST/products/add

Add Products To Customer

This endpoint allows you to add billables to a customer

Request

POST

/products/add

curl --location --request POST 'http://localhost:5000/products/add' \
--header 'Content-Type: application/json' \
--data-raw '{
    "organizationId": "9A6D20A4DB674341BDC290E1E88126BD", 
    "customerId": "0A1DF9A20464473F8EFD822C19CBF763", 
    "products" : [
        {
            "productGroupId": "0F0B96DB38B4439281F6E7D685674DE1",
            "pricingId": "48612F2D9E5C4F878C244304510B9732", 
            "startDate": "1677877954", 
            "options" : {
                "proRate": true,
                "discount": 0.00, 
                "trial": { 
                    "trialPrice": 0, 
                    "trialDuration": 2, 
                    "trialFrequency": "months"
                }
            }
        }, 
        {
            "skewId": "747B5664399E4D1DA06E6FB6D6D49529", 
            "startDate": "1677877954", 
            "options" : {
                "endDate": "",
                "proRate": true,
                "discount": 0.00,
                "trial": { 
                    "trialPrice": 0, 
                    "trialDuration": 2, 
                    "trialFrequency": "months"
                }
            }
        }

    ], 
    "customData": {
        "emails": 200, 
        "texts": 1500, 
        "hasTakenReference": true
    }
}'

Response

{
"data": {
    "erroredProducts": [],
    "successProducts": [
        {
            "amount": 35.0,
            "billUpFront": null,
            "contractDuration": null,
            "createdAt": null,
            "customerId": "0A1DF9A20464473F8EFD822C19CBF763",
            "cyclePeriod": "Monthly",
            "cycles": null,
            "discount": 0,
            "endDate": null,
            "expires": null,
            "fee": null,
            "id": "914E3609D8934E2398565AB43602F86D",
            "invoiceId": null,
            "isOneTime": null,
            "isProRate": null,
            "nextBillingDate": "1677877954",
            "organizationId": "9A6D20A4DB674341BDC290E1E88126BD",
            "previousBillingDate": null,
            "productGroupId": "0F0B96DB38B4439281F6E7D685674DE1",
            "productId": "3C11185BABDB48FCA8C6F41B5ED4763E",
            "productName": "Advanced Analytics",
            "productType": "product",
            "shouldTrialRecur": null,
            "startDate": "1677877954",
            "transactionLinkId": null,
            "trialAmount": null,
            "trialCycle": null,
            "trialCyclePeriod": null,
            "updateAt": null
        },
        {
            "amount": 6.0,
            "billUpFront": null,
            "contractDuration": null,
            "createdAt": null,
            "customerId": "0A1DF9A20464473F8EFD822C19CBF763",
            "cyclePeriod": "Monthly",
            "cycles": null,
            "discount": 0,
            "endDate": null,
            "expires": null,
            "fee": null,
            "id": "B390A01969F9474897F8A68C70723CB1",
            "invoiceId": null,
            "isOneTime": null,
            "isProRate": null,
            "nextBillingDate": "1677877954",
            "organizationId": "9A6D20A4DB674341BDC290E1E88126BD",
            "previousBillingDate": null,
            "productGroupId": "018A08C6C0DE4AD6BDC27F3428DF271F",
            "productId": "747B5664399E4D1DA06E6FB6D6D49529",
            "productName": "Emails Sent",
            "productType": "product",
            "shouldTrialRecur": null,
            "startDate": "1677877954",
            "transactionLinkId": null,
            "trialAmount": null,
            "trialCycle": null,
            "trialCyclePeriod": null,
            "updateAt": null
        }
    ]
},
"status": "success"
}

GET/products/search

Search Product By Name

This endpoint allows you to add billables to a customer

Request

GET

/products/search

curl --location --request GET 'http://localhost:5000/products/search/37E1A66F6C464712B169251195C7F721?search={PRODUCTNAME}'

Response

{
"data": {
    "pricing": [
        {
            "createdAt": "2023-01-16 04:12:33",
            "endDate": null,
            "id": "133454783F74403FBADCC071FFF30BCF",
            "organizationId": "9A6D20A4DB674341BDC290E1E88126BD",
            "pricingName": "2022 Pricing",
            "productGroupId": "01F86CF0F2ED43BDBFD6749A25CE0DF4",
            "startDate": null,
            "updatedAt": "2023-01-16 04:12:33"
        },
        {
            "createdAt": "2023-01-16 04:17:43",
            "endDate": null,
            "id": "74B7AEB9D0754B6F92C91B032B85B6C5",
            "organizationId": "37E1A66F6C464712B169251195C7F721",
            "pricingName": "2023 Pricing",
            "productGroupId": "01F86CF0F2ED43BDBFD6749A25CE0DF4",
            "startDate": null,
            "updatedAt": "2023-01-16 04:17:43"
        }
    ],
    "product": {
        "billingCycle": "Monthly",
        "createdAt": "2022-12-09 17:26:28",
        "id": "01F86CF0F2ED43BDBFD6749A25CE0DF4",
        "name": "DV Pro Monthly Subscription",
        "organizationId": "37E1A66F6C464712B169251195C7F721",
        "price": null,
        "pricingFormula": null,
        "productGroupId": "DB1A489296B747D0808811C4EF837395",
        "productType": null,
        "updateAt": "2022-12-09 17:26:28",
        "variable": "Constituents"
    },
    "skews": {
        "133454783F74403FBADCC071FFF30BCF": [
            {
                "billingCycle": "Monthly",
                "createdAt": "2023-01-03 03:30:09",
                "endDate": null,
                "groupName": "DV Pro Monthly Subscription",
                "id": "2A7F12DBDF8C41F6B97EA0C167A87A23",
                "levelName": "10,000 - 15,000",
                "lower": 5001.0,
                "organizationId": "37E1A66F6C464712B169251195C7F721",
                "price": 570.0,
                "pricingFormula": null,
                "pricingId": "133454783F74403FBADCC071FFF30BCF",
                "productGroupId": "01F86CF0F2ED43BDBFD6749A25CE0DF4",
                "skewName": "2022 Pricing",
                "startDate": null,
                "updateAt": "2023-01-03 03:30:09",
                "upper": 15000.0,
                "variable": "Constituents"
            },
            ...
        ],
        "74B7AEB9D0754B6F92C91B032B85B6C5": [
            {
                "billingCycle": "Monthly",
                "createdAt": "2023-01-16 04:17:43",
                "endDate": null,
                "groupName": "DV Pro Monthly Subscription",
                "id": "5F8BAC6795374F19A2F5B7E00AA1634F",
                "levelName": "20,001 - 25,000",
                "lower": 20001.0,
                "organizationId": "37E1A66F6C464712B169251195C7F721",
                "price": 853.0,
                "pricingFormula": null,
                "pricingId": "74B7AEB9D0754B6F92C91B032B85B6C5",
                "productGroupId": "01F86CF0F2ED43BDBFD6749A25CE0DF4",
                "skewName": "2023 Pricing",
                "startDate": null,
                "updateAt": "2023-01-16 04:17:43",
                "upper": 25000.0,
                "variable": "Constituents"
            },
            ...
        ]
    }
},
"status": "success"
}