POST

/v1/prices

X-Api-Key*

​
Usage

The first time that you call this endpoint for a given IP address and user ID, Corrily calculates the price. On subsequent calls (with the same IP address and user ID), Corrily returns the original calculated price.

See Calculate price API examples for examples of how this endpoint is commonly used.

​
Price localization

If you’re only using Corrily for price localization (i.e. you are not doing price optimization), this is the endpoint that you call in order to get localized prices.

​
Price optimization

If you’re also doing price optimization, this is the endpoint you call to get optimized prices.

As explained in Price optimization overview, Corrily either returns an experimental price or a control price which will be used to benchmark the experimental prices.

Experimental prices are affected by the following factors:

  • The (potential) customer’s location, which is inferred from their IP address
  • Any user features that you have provided
  • The outcomes of previous price experiments
  • The upper and lower bounds that you defined in the Corrily Dashboard

​
Body Params

user_id
string

A User ID. Only required if no ip is provided and get_ip_from_request is false.

productsrequired
string[]

The product IDs that you want to calculate prices for. In general, you probably want to include the product IDs for all the product offerings that you intend to show your visitor. The response from Corrily will contain the display price for each product. For example, if you provide ["monthly", "annual"], Corrily returns price data for your monthly and annual products. Product IDs are created by Corrily when you set up your Corrily account. Email support@corrily.com if you don’t know yours.

package_id
string

If packaging segmentation is enabled, package id can be passed to get the products for a package. That way the products shown themselves will be based on the package segmentation. When package segmentation is enabled, the products parameter is optional. If there is no pacakge segmentation defined for given country, audience, and no package_id, products are specified in request, an error will be returned.

ip
string

An IPv4 or IPv6 address. Corrily uses this as the user ID if no user_id is provided. ip is only required if no user_id is provided and get_ip_from_request is false. Examples: 187.106.3.73 (IPv4), 2804:14d:ac91:8286:efcb:851f:b59f:fffc (IPv6).

get_ip_from_request
boolean

If true, Corrily sources the user’s IP from this request. get_ip_from_request therefore only works correctly when the Corrily API request is made from a client device.

country
string

A two-letter (Alpha-2) ISO 3166 country code. Example: US

features
object

An object containing key-value pairs of arbitrary strings that represent features of this user which may affect their optimal price. See User features. Example: {"platform": "ios"}

integrations
string[]

The payment gateways to return integration objects for. Accepted values: stripe, paypal, chargebee

currency
string

A currency you wish the price to be tied to. Currencies do not need to match the passed country. For example, it is possible to return a price in EUR for someone based in the Unites Sates. Note that the country-adjusted price will be returned, regardless of the currency set.

override_currency
boolean

Will override the currency of any previously saved price and instead return the price in the currency provided. If set to true, a currency param must be passed. Unlike override the price amount will not be recomputed.

run_experiment
boolean

If set to false, will make sure no experiment is run.

coupons
object

Optional product id to coupon id mapping to explicitly specify the coupon to be applied in the pricing. Coupons feature needs to be enabled for this. example {"product_id_1": "coupon_id_1"}. Multiple coupons can be applied by a comma-delimited string, for example: {"product_id_1": "coupon_id_1,coupon_id2"}

​
Response

success
boolean

Whether or not the request completed successfully.

user_id
string

The user ID that you provided when you called calculate price, or the user’s IP address (if you did not provide a user ID).

package_id
string

The package ID that was used to get the products.

country
enum

The country that the price data is associated to. If you did not specify a country when calling calculate price, the country value provided here in the response is inferred from the user’s IP address.

currency
enum

The currency that the price data is associated to. Tip: check if products. {id}.display.price meets your needs before manually constructing a display price with this field.

currency_symbol
string

The currency symbol that the price data is associated to. Tip: check if products.{id}.display.price meets your needs before manually constructing a display price with this field.

products
object

The price data for each of the products that you specified when you called calculate price. The placeholder {id} below represents your product ID(s). See Setup to learn how to create product IDs.

variants
object

Price experimentation metadata. If you are not doing price experimentation, you can ignore this object.

{
  "success": true,
  "user_id": "193.37.32.232",
  "country": "SG",
  "currency": "SGD",
  "currency_symbol": "S$",
  "products": {
    "monthly": {
      "price": 27,
      "price_usd": 20.059360849328197,
      "interval": "month",
      "interval_count": 1,
      "display": {
        "price": "S$ 27",
        "reference_interval_price": "S$ 27",
        "price_with_baseline_strike": "S$ 27",
        "discount_to_baseline": 0
      },
      "integrations": {
        "stripe": {
          "currency": "SGD",
          "amount": 2700,
          "formatted": "S$ 27"
        }
      }
    },
    "annual": {
      "price": 144,
      "price_usd": 106.98325786308372,
      "interval": "year",
      "interval_count": 1,
      "display": {
        "price": "S$ 144",
        "reference_interval_price": "S$ 12",
        "price_with_baseline_strike": "S$ 12",
        "discount_to_baseline": 0
      },
      "integrations": {
        "stripe": {
          "currency": "SGD",
          "amount": 14400,
          "formatted": "S$ 144"
        }
      },
      "coupon": {
        "id": "coupon_id_392",
        "type": "percentage",
        "value": 10,
        "coupon_source": "chargebee",
        "external_coupon_id": "chargebee_coupon_392",
        "currency_code": "USD",
        "valid_till": "2022-02-07 15:49:49",
        "display": {
          "local_currency_symbol": "€",
          "interval_local_price_formatted": "9 €",
          "local_price_formatted": "9 €",
          "usd_price_formatted": "$11",
          "local_price_formatted_with_baseline_strike": "9 €",
          "pct_discount_to_baseline": 0.0
        }
      }
    }
  },
  "variants": {
    "experimented_on": true
  }
}

curl --request POST \
     --url https://client.corrily.com/v1/prices \
     --header 'Content-Type: application/json' \
     --data '
{
     "user_id": "string",
     "products": [
          "string"
     ],
     "ip": "string",
     "get_ip_from_request": true,
     "country": "string",
     "integrations": [
          "string"
     ],
     "currency": "string",
     "override": true,
     "run_experiment": true
}
'
Recommendation EngineIdentify Call