POST /invitations
Create one or more Invitations

Create one or more Invitations.
To create multiple Invitations, use the invitations parameter, which is an array of hashes containing the necessary parameters (examples provided). Keep in mind that the maximum number of Invitations you can create in one request is 100. If you submit more than 20 invitations in a single request, only 20 will be included in the response and the rest will be created asynchronously in the background. To receive all data synchronously in the response, submit batches of 20 invitations at a time.

Supported Formats

json

Params

Param name Description
invitation
required

Invitation data. An invitation is typically created when an order has been processed and the product has been shipped to the customer, or when some kind of transaction has been completed. An invitation is normally an email or sms message to the customer asking for their rating and review.


Value:

Must be a Hash
invitation[buyer_email]
required

The customers email address


Value:

Must be a String
invitation[buyer_name]
required

The customers full name (an actual full name is required, nicknames/alias/etc are not accepted)


Value:

Must be a String
invitation[lang]
required

A two letter code of the language that will be used in emails to the customer. Available values are: br, cz, de, dk, en, es, et, fi, fr, it, ja, lv, nl, no, pl, ru, se, sk


Value:

Must be a String
invitation[buyer_phone]
recommended

The customers phone number. Needs to be a fully qualified phone number including country code, but without any special characters like (, ), -, etc. Example: +47123456789


Value:

Must be a String
invitation[template]
optional

The name of the template that will be used in emails to a customer. Available values:
confirm -> email1 - single CTA-button
review -> email2 - stars in email
confirm_and_review -> email1 first, then email2
service -> service review email.

Please note that we recommend this to be empty! Lipscore has procedures in place to select the right template at the right time.


Value:

Must be a String
invitation[purchased_at]
recommended

Date when the order was placed / transaction was made. The current date is used by default. Specify it when you need a different date only.

Purchased at- date is displayed in the invitations and in the widgets.


Value:

Must be a String
invitation[shipped_at]
recommended

Date when the product or service was actually delivered to the customer (either shipped from a warehouse or when the service was delivered). Invitations are scheduled based on this date. If this date is empty, invitations will be scheduled based on the purchased_at date.


Value:

Must be a String
invitation[source_id]
recommended

An ID of where the invitation/order originates from, for example the ID of a physical store in a chain of many stores.


Value:

Must be a String
invitation[source_name]
recommended

The name of where the invitation/order originates from, possible values could be for example “Webshop” or “Storo Shopping Center” or “Conference 22nd of June 2022”. This name will potentially be visible for customers so it should be in a “proper” readable format.


Value:

Must be a String
invitation[parent_source_id]
recommended

The ID of the Parent source in a hierarchy of sources. for example the ID of a Region or Area, if collecting reviews from of physical stores.


Value:

Must be a String
invitation[parent_source_name]
recommended

The name of the Parent source in a hierarchy of sources. Possible values could be for example “North”, “South”, etc. The name will potentially be visible for customers so it should be in a “proper” readable format.


Value:

Must be a String
invitation[internal_order_id]
optional

The orders internal ID in your webshop. Used for mapping ratings and reviews in Lipscore to your order data.


Value:

Must be a String
invitation[internal_customer_id]
optional

The customers internal ID in your webshop. Used for mapping ratings and reviews in Lipscore to your customer data.


Value:

Must be a String
invitation[internal_attr_1]
optional

An internal attribute from your webshop you need for mapping ratings and reviews


Value:

Must be a String
invitation[internal_attr_2]
optional

An internal attribute from your webshop you need for mapping ratings and reviews


Value:

Must be a String
invitation[internal_attr_3]
optional

An internal attribute from your webshop you need for mapping ratings and reviews


Value:

Must be a String
invitation[internal_attr_4]
optional

An internal attribute from your webshop you need for mapping ratings and reviews


Value:

Must be a String
invitation[internal_attr_5]
optional

An internal attribute from your webshop you need for mapping ratings and reviews


Value:

Must be a String
products[]
required

An array of purchased products. Each element of the array is a hash of product params.


Value:

Must be an Array of nested elements
products[][internal_id]
required

The products internal ID in your webshop (referred to as Product ID in Lipscore backend) (the product will also get a Lipscore specific product ID, usually referred to as “id”).

It is strongly recommended to use a “Parent” Product ID that is identical for all variants of the same product. By using the same ID on all variants, the average rating and list of reviews will be the same for all variants.


Value:

Must be a String
products[][url]
required

The fully qualified URL (including https://) of the product details page in your webshop.

An accurate Product URL is a requirement for displaying ratings and reviews on Google Shopping.


Value:

Must be a String
products[][name]
required

The full name of the product (not including brand name)


Value:

Must be a String
products[][variant_id]
recommended

The ID of the variant of the product, typically an SKU or similar. The variant_id will typically be different for a green shirt and a blue shirt of the same model.


Value:

Must be a String
products[][variant_name]
recommended

The name of the variant of the product, including size/color information if possible.


Value:

Must be a String
products[][brand]
recommended

The product brand (i.e. “Apple” for an iPhone).

Brand is useful for reporting purposes.


Value:

Must be a String
products[][sku_values]
recommended

One or more Product SKU values of the product variant that has been purchased


Value:

Must be an array of String
products[][gtin]
recommended

One or more Product GTIN values.

GTIN is a requirement for displaying ratings and reviews on Google Shopping.


Value:

Must be one of: String, Array.
products[][mpn]
recommended

The product Manufacturer Part Number value.

MPN is recommended for displaying ratings and reviews on Google Shopping.


Value:

Must be one of: String, Array.
products[][image_url]
optional

The product image URL (full path)


Value:

Must be a String
products[][price]
recommended

The Product price without currency.

The price is used for reporting purposes and for displaying in Google organic search results


Value:

Must be a Numeric
products[][currency]
recommended

The price currency.

The currency is used for reporting purposes and for displaying in Google organic search results


Value:

Must be a String
products[][category]
recommended

The product category. Can be a single category name or a hierarchy structure separated by a delimiter such as – or /

Category is required for using the Product Attributes feature, and for blocking specific categories.


Value:

Must be a String
api_key
required

API key (a 24 character unique code)


Value:

Must be a String

Examples

POST /invitations?api_key=889c3f3e4b6ac67269261324


Single Invitation
Request
{
  "invitation": {
    "buyer_email": "johndoe@example.com",
    "buyer_name": "John Doe",
    "lang": "en",
    "internal_order_id": "778203",
    "internal_customer_id": "84021",
    "purchased_at": "2022-12-24T14:48:43.874Z",
    "shipped_at": "2022-12-26T14:48:43.874Z",
    "source_id": "storo1",
    "source_name": "Storo Shopping Center",
    "parent_source_id": "south",
    "parent_source_name": "South",
    "internal_attr_1": "Attribute 1",
    "internal_attr_2": "Attribute 2",
    "internal_attr_3": "Attribute 3",
    "internal_attr_4": "Attribute 4",
    "internal_attr_5": "Attribute 5"
  },
  "products": [
    {
      "internal_id": "4716051",
      "url": "http://mysite.com/products/lipscore-ultra-i9/6268A",
      "name": "Lipscore Ultra i9 SmartPhone",
      "variant_id": "Lipscore_4716051_Black",
      "variant_name": "Lipscore Ultra i9 SmartPhone Black",
      "brand": "Lipscore",
      "sku_values": [
        "Lipscore_4716051",
        "Lipscore_4716051_Black"
      ],
      "gtin": "3234567890126",
      "mpn": "XTR-4590A",
      "image_url": "http://mysite.com/images/lipscore-ultra-i9/6268A.png",
      "price": "200",
      "currency": "USD",
      "category": "smartphones"
    }
  ]
}


Response
{
  "invitation": {
    "id": 1521893,
    "invitation_token": "8475e5d62d5b4a9d72cfbff7a6440ccf820ee17d",
    "created_at": "2022-12-24T14:48:43.932Z",
    "purchased_at": "2022-12-24T14:48:43.874Z",
    "lang": "en",
    "cancelled": false,
    "invitation_date": "2022-12-25T14:48:43.874Z",
    "invitation_sent_at": null,
    "invitation_clicked_at": null,
    "second_invitation_date": null,
    "second_invitation_sent_at": null,
    "second_invitation_clicked_at": null,
    "invitation_type": "product",
    "landing_url": "http://mysite.com/products/lipscore-ultra-i9/6268A?lipscore_token=eyJwdXJjaGFzZSI6eyJyZW1pbmRlcl90b2tlbiI6Ijg0NzVlNWQ2MmQ1YjRhOWQ3MmNmYmZmN2E2NDQwY2NmODIwZWUxN2QiLCJoYXNfZGlzY291bnQiOnRydWUsInByb2R1Y3RzIjpbeyJpZCI6MTgwLCJuYW1lIjoidGVzdHAzIG5hbWUifV0sImFiX3Rlc3QiOm51bGx9LCJzZXR0aW5ncyI6eyJyYXRpbmdfdHlwZSI6IjUtc3RhcnMiLCJyYXRpbmdfc3Rhcl90eXBlIjoidGhpY2siLCJyYXRpbmdfc3Rhcl9jb2xvciI6IiMyYjk5Y2YiLCJyYXRpbmdfd2lkZ2V0X3R5cGUiOiJjb21wYWN0IiwicmF0aW5nX3NtYWxsX3R5cGUiOiIxLXN0YXIiLCJmZWF0dXJlcyI6WyJyYXRpbmdzX3Jldmlld3MiLCJyYXRpbmdzX3Jldmlld3MiLCJyZW1vdmVfYnJhbmRpbmciLCJsb3dfdHJpZ2dlciJdfX0=&lipscore_received=1",
    "landing_unreceived_url": "http://mysite.com/products/lipscore-ultra-i9/6268A?lipscore_token=eyJwdXJjaGFzZSI6eyJyZW1pbmRlcl90b2tlbiI6Ijg0NzVlNWQ2MmQ1YjRhOWQ3MmNmYmZmN2E2NDQwY2NmODIwZWUxN2QiLCJoYXNfZGlzY291bnQiOnRydWUsInByb2R1Y3RzIjpbeyJpZCI6MTgwLCJuYW1lIjoidGVzdHAzIG5hbWUifV0sImFiX3Rlc3QiOm51bGx9LCJzZXR0aW5ncyI6eyJyYXRpbmdfdHlwZSI6IjUtc3RhcnMiLCJyYXRpbmdfc3Rhcl90eXBlIjoidGhpY2siLCJyYXRpbmdfc3Rhcl9jb2xvciI6IiMyYjk5Y2YiLCJyYXRpbmdfd2lkZ2V0X3R5cGUiOiJjb21wYWN0IiwicmF0aW5nX3NtYWxsX3R5cGUiOiIxLXN0YXIiLCJmZWF0dXJlcyI6WyJyYXRpbmdzX3Jldmlld3MiLCJyYXRpbmdzX3Jldmlld3MiLCJyZW1vdmVfYnJhbmRpbmciLCJsb3dfdHJpZ2dlciJdfX0=&lipscore_received=0",
    "internal_order_id": "778203",
    "internal_customer_id": "84021",
    "internal_attr_1": "Attribute 1",
    "internal_attr_2": "Attribute 2",
    "internal_attr_3": "Attribute 3",
    "internal_attr_4": "Attribute 4",
    "internal_attr_5": "Attribute 5",
    "source_id": "storo1",
    "source_name": "Storo Shopping Center",
    "parent_source_id": "south",
    "parent_source_name": "South",
    "products": [
      {
        "id": "1807875",
        "name": "Lipscore Ultra i9 SmartPhone",
        "landing_star_urls": [
          "http://mysite.com/products/lipscore-ultra-i9/6268A?lipscore_received=1&lipscore_token=PMRGS3TWNF2GC5DJN5XCEOT3EJZGK3LJNZSGK4S7ORXWWZLOEI5CENTBMFRTAODFHE2TGMTFMFTGEMTGMY2TMOJSG44GCNBUGA3GINDGGYZDQOBXHA3DKIRMEJUGC427MRUXGY3POVXHIIR2ORZHKZJMEJZGK3LJNZSGK4S7ORSW24DMMF2GKX3JMQRDUMRMEJYHE33EOVRXI4ZCHJNXWITJMQRDUMRVG4YCYITQOJXWI5LDORPWS3TTORQW4Y3FL5UWIIR2GI3DKNJMEJXGC3LFEI5CE5DFON2HANJSEBXGC3LFOMRH2XJMEJQWEX3UMVZXIIR2NZ2WY3D5PUaaaaaa&ls_origin=email&ls_pre_rate_p=2570&ls_pre_rate_pi=2655&ls_pre_rate_v=2&ls_type=email2",
          "http://mysite.com/products/lipscore-ultra-i9/6268A?lipscore_received=1&lipscore_token=PMRGS3TWNF2GC5DJN5XCEOT3EJZGK3LJNZSGK4S7ORXWWZLOEI5CENTBMFRTAODFHE2TGMTFMFTGEMTGMY2TMOJSG44GCNBUGA3GINDGGYZDQOBXHA3DKIRMEJUGC427MRUXGY3POVXHIIR2ORZHKZJMEJZGK3LJNZSGK4S7ORSW24DMMF2GKX3JMQRDUMRMEJYHE33EOVRXI4ZCHJNXWITJMQRDUMRVG4YCYITQOJXWI5LDORPWS3TTORQW4Y3FL5UWIIR2GI3DKNJMEJXGC3LFEI5CE5DFON2HANJSEBXGC3LFOMRH2XJMEJQWEX3UMVZXIIR2NZ2WY3D5PUaaaaaa&ls_origin=email&ls_pre_rate_p=2570&ls_pre_rate_pi=2655&ls_pre_rate_v=4&ls_type=email2",
          "http://mysite.com/products/lipscore-ultra-i9/6268A?lipscore_received=1&lipscore_token=PMRGS3TWNF2GC5DJN5XCEOT3EJZGK3LJNZSGK4S7ORXWWZLOEI5CENTBMFRTAODFHE2TGMTFMFTGEMTGMY2TMOJSG44GCNBUGA3GINDGGYZDQOBXHA3DKIRMEJUGC427MRUXGY3POVXHIIR2ORZHKZJMEJZGK3LJNZSGK4S7ORSW24DMMF2GKX3JMQRDUMRMEJYHE33EOVRXI4ZCHJNXWITJMQRDUMRVG4YCYITQOJXWI5LDORPWS3TTORQW4Y3FL5UWIIR2GI3DKNJMEJXGC3LFEI5CE5DFON2HANJSEBXGC3LFOMRH2XJMEJQWEX3UMVZXIIR2NZ2WY3D5PUaaaaaa&ls_origin=email&ls_pre_rate_p=2570&ls_pre_rate_pi=2655&ls_pre_rate_v=6&ls_type=email2",
          "http://mysite.com/products/lipscore-ultra-i9/6268A?lipscore_received=1&lipscore_token=PMRGS3TWNF2GC5DJN5XCEOT3EJZGK3LJNZSGK4S7ORXWWZLOEI5CENTBMFRTAODFHE2TGMTFMFTGEMTGMY2TMOJSG44GCNBUGA3GINDGGYZDQOBXHA3DKIRMEJUGC427MRUXGY3POVXHIIR2ORZHKZJMEJZGK3LJNZSGK4S7ORSW24DMMF2GKX3JMQRDUMRMEJYHE33EOVRXI4ZCHJNXWITJMQRDUMRVG4YCYITQOJXWI5LDORPWS3TTORQW4Y3FL5UWIIR2GI3DKNJMEJXGC3LFEI5CE5DFON2HANJSEBXGC3LFOMRH2XJMEJQWEX3UMVZXIIR2NZ2WY3D5PUaaaaaa&ls_origin=email&ls_pre_rate_p=2570&ls_pre_rate_pi=2655&ls_pre_rate_v=8&ls_type=email2",
          "http://mysite.com/products/lipscore-ultra-i9/6268A?lipscore_received=1&lipscore_token=PMRGS3TWNF2GC5DJN5XCEOT3EJZGK3LJNZSGK4S7ORXWWZLOEI5CENTBMFRTAODFHE2TGMTFMFTGEMTGMY2TMOJSG44GCNBUGA3GINDGGYZDQOBXHA3DKIRMEJUGC427MRUXGY3POVXHIIR2ORZHKZJMEJZGK3LJNZSGK4S7ORSW24DMMF2GKX3JMQRDUMRMEJYHE33EOVRXI4ZCHJNXWITJMQRDUMRVG4YCYITQOJXWI5LDORPWS3TTORQW4Y3FL5UWIIR2GI3DKNJMEJXGC3LFEI5CE5DFON2HANJSEBXGC3LFOMRH2XJMEJQWEX3UMVZXIIR2NZ2WY3D5PUaaaaaa&ls_origin=email&ls_pre_rate_p=2570&ls_pre_rate_pi=2655&ls_pre_rate_v=10&ls_type=email2"
        ],
        "review_text": null,
        "attributes": [],
        "image_url": "http://mysite.com/images/lipscore-ultra-i9/6268A.png"
      }
    ],
    "user": {
      "id": 56634,
      "name": "John Doe",
      "avatar_thumb_url": "https://static.lipscore.com/avatars/000/000/000/thumb_000000005936.jpg",
      "short_name": "John",
      "email": "johndoe@example.com"
    }
  }
}

?api_key=889c3f3e4b6ac67269261324


Multiple Invitations
Request
{
  "invitations": [
    {
      "invitation": {},
      "products": []
    },
    {
      "invitation": {},
      "products": []
    }
  ]
}


Response
[
  {
    "invitation": {}
  },
  {
    "invitation": {}
  }
]