MAP pricing management

The MAP pricing management APIs allow you to access, retrieve, and display Minimum Advertised Price (MAP) policies and promotions for your store. This ensures compliance and transparency across your sales channels.

MAP policies

MAP policies define the lowest price at which a product can be advertised. Use these APIs to list available MAP policies or retrieve the details of a specific policy.

List MAP policies

Use this endpoint to retrieve a paginated list of MAP policies, filtered by different criteria.

Endpoint: GET /api/map-policies

Query parameters

Name	Required	Description
`sort`	No	Sorts by creation or update timestamp.
`page_size`	No	Sets the number of results per page.
`page`	No	Sets the page number.
`filter[field]`	No	Filters results by specific fields (e.g., `title`).
`filter[trashed]`	No	Includes soft-deleted records. Values: `with`, `only`, or `without`.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/map-policies?sort=-title&page=2&page_size=20&filter%5Bfield%5D=81a17e93-d2b4-4f72-958c-734a88b3942f&filter%5Btrashed%5D=with" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": [
    {
      "id": 42,
      "company_id": 7,
      "title": "Hawkstone Tactical MAP Policy 2024",
      "map_policy_type_id": 2,
      "map_advertising_pricing": {
        "code": "MAP_MINIMUM",
        "description": "MAP is Minimum Price"
      },
      "published": false,
      "contact_email": null,
      "unrestricted": false,
      "allow_add_to_cart": false,
      "allow_international_shipments": "NO",
      "allow_free_shipping": "NO",
      "allow_sub_distribution": "NO",
      "allow_drop_shipping": "NO",
      "start_date": "2024-09-01",
      "end_date": "2024-09-30",
      "file_url": null,
      "contents": null,
      "created_at": "2024-08-28T13:45:00.000000Z",
      "updated_at": "2024-08-28T13:45:00.000000Z"
    },
    {
      "id": 58,
      "company_id": 7,
      "title": "Redstone Firearms MAP Policy 2024",
      "map_policy_type_id": 3,
      "map_advertising_pricing": {
        "code": "CALL_PRICE",
        "description": "Call for Price"
      },
      "published": true,
      "contact_email": null,
      "unrestricted": true,
      "allow_add_to_cart": true,
      "allow_international_shipments": "REQUIRES_APPROVAL",
      "allow_free_shipping": "YES",
      "allow_sub_distribution": "REQUIRES_APPROVAL",
      "allow_drop_shipping": "REQUIRES_APPROVAL",
      "start_date": null,
      "end_date": null,
      "file_url": "https://bfg-atlas.s3.amazonaws.com/map.policies/files/1623859273-sample.txt",
      "contents": "{\"statement\": \"To support brand integrity and protect market value.\",\"advertising_applications\": [\"Online Ads\",\"Retail Circulars\",\"Flyers\"],\"advertising_policy\": \"Any listed price below the minimum violates this MAP policy.\",\"violations\": [{\"violation\": \"First Violation\",\"type\": \"ONLINE LISTING\",\"resulting_action\": \"Formal Warning\"}]}",
      "created_at": "2024-08-29T09:22:10.000000Z",
      "updated_at": "2024-08-30T11:10:45.000000Z"
    }
  ],
  "links": {
    "first": "http://127.0.0.1:8000/api/companies/7/policies?page=1",
    "last": "http://127.0.0.1:8000/api/companies/7/policies?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "http://127.0.0.1:8000/api/companies/7/policies?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "http://127.0.0.1:8000/api/companies/7/policies",
    "per_page": 10,
    "to": 2,
    "total": 2
  }
}

Get a MAP policy

Use this endpoint to retrieve the full details of a specific MAP policy using its policy_id. To display formatted policy language, parse the contents field of a MAP policy.

Endpoint: GET /api/map-policies/{policy_id}

URL parameters

policy_id: Required. Unique ID of the policy.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/map-policies/37" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": {
    "id": 37,
    "company_id": 14,
    "title": "Silverlake Defense MAP Policy 2024",
    "map_policy_type_id": 3,
    "map_advertising_pricing": {
      "code": "MAP_MINIMUM",
      "description": "MAP is Minimum Price"
    },
    "published": false,
    "contact_email": "[email protected]",
    "unrestricted": true,
    "allow_add_to_cart": false,
    "allow_international_shipments": "REQUIRES_APPROVAL",
    "allow_free_shipping": "YES",
    "allow_sub_distribution": "NO",
    "allow_drop_shipping": "REQUIRES_APPROVAL",
    "start_date": "2023-08-01",
    "end_date": "2023-08-31",
    "file_url": "https://atlas.com/files/9876543210-silverlake-policy.pdf",
    "contents": "{\n  \"statement\": \"To maintain consistent pricing across all channels and protect the brand’s perceived value.\",\n  \"advertising_applications\": [\n    \"Email Campaigns\",\n    \"Print Ads\",\n    \"Flyers\",\n    \"In-store Signage\"\n  ],\n  \"advertising_policy\": \"Any advertised price below the minimum is a direct violation of this MAP policy.\",\n  \"violations\": [\n    {\n      \"violation\": \"First Violation\",\n      \"type\": \"DIGITAL (WEBSITE, SOCIAL)\",\n      \"resulting_action\": \"Notice of Violation\"\n    }\n  ]\n}",
    "created_at": "2024-02-20T10:15:00.000000Z",
    "updated_at": "2024-02-20T10:15:00.000000Z"
  }
}

MAP promotion products

MAP promotions allow you to list specific products governed by promotional MAP policies. These APIs help you fetch all participating products or query a single product in a promotion.

Identifying your `promotion_id`

The promotion_id is a required field for the List Promotion Products and Get a Promotion Product APIs.

Go to BFG and on the sidebar, select Products > MAP Promotions.
In the row of a MAP promotion, click Edit.
View the URL of the page. The number is the promotion_id. For example, in <https://bfg.johndoe.app/#/promotions/1>, 1 is the promotion_id.

List promotion products

Get a list of all products associated with a MAP promotion.

Endpoint: GET /api/map-promotions/{promotion_id}/products

URL parameters

promotion_id: Required. Unique ID of the MAP promotion.

Query parameters

Name	Required	Description
`page_size`	No	Sets the number of results per page.
`page`	No	Sets the page number.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/map-promotions/57/products?page=2&page_size=20" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": [
    {
      "id": 1,
      "product_id": 101,
      "title": "12V AC Power Adapter w/Right-Angle Plug – 5ft",
      "upc": "019283746511",
      "map_promotion_id": 57,
      "created_at": "2024-11-16 07:23:58"
    },
    {
      "id": 2,
      "product_id": 102,
      "title": "Green Safety Cone – Vantage Series (Gen 2)",
      "upc": "019283700988",
      "map_promotion_id": 57,
      "created_at": "2024-11-17 22:53:44"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 2
  }
}

Get a promotion product

Retrieve the details of a specific product listed in a MAP promotion.

Endpoint: GET /api/map-promotions/{promotion_id}/products/{product_id}

URL parameters

Name	Required	Description
`promotion_id`	Yes	ID of the MAP promotion.
`product_id`	Yes	ID of the product.

Example request

curl --request GET \
  --get "https://api-sandbox.buyingfreedom.app/api/map-promotions/73/products/19" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Example response

{
  "data": {
    "id": 19,
    "product_id": 502,
    "title": "6' USB-C Charging Cable with Angled Connector",
    "upc": "023987654321",
    "map_promotion_id": 73,
    "created_at": "2024-11-17 22:53:44"
  }
}

MAP policies

List MAP policies

Query parameters

Example request

Example response

Get a MAP policy

URL parameters

Example request

Example response

MAP promotion products

Identifying your promotion_id

List promotion products

URL parameters

Query parameters

Example request

Example response

Get a promotion product

URL parameters

Example request

Example response

Identifying your `promotion_id`