Integration API reference

The Integration API allows trusted secure applications to access the entire marketplace data: all users, listings, transactions, messages, etc. Such trusted applications are for example applications that run in your own backend systems or applications meant to be executed by authorized marketplace operators.

Authentication

Example request:

$ curl -X GET 'https://flex-integ-api.sharetribe.com/v1/integration_api/marketplace/show' \
    -H 'Authorization: bearer ACCESS_TOKEN'

Every call to the Integration API must be made with a valid access token included in the API request. The access token must be provided via Authorization HTTP header in each API request in the form of:

Authorization: bearer ACCESS_TOKEN

API clients can obtain access tokens directly via the Authentication API or use the Sharetribe Integration SDK, which provides convenience methods of handling authentication and tokens. Using the SDK is recommended over direct API access.

Sharetribe Integration SDK

const flexIntegrationSdk = require('sharetribe-integration-sdk');

const integrationSdk = flexIntegrationSdk.createInstance({
  clientId: '<Your Client ID here>',
  clientSecret: '<Your client secret here>'
});

Sharetribe Integration SDK is available at the moment for JavaScript and provides the easiest way to authenticate and use the Integration API.

Revoking the refresh token

integrationSdk.revoke().then(res => {
  console.log("Refresh token revoked.")
});

The Integration SDK is ready for use as soon as it is instantiated, as illustrated in the example on the right. It automatically maintains internally a refresh token, which serves as a session secret. In some cases, you may wish to explicitly revoke the refresh token. You can do so using the .revoke() method of the SDK.

Rate limits

The following table lists the Integration API request rate and concurrency limits.

Note that some of the limits apply to specific marketplace environments.

Marketplace environment(s)	Endpoint(s)	Limit	Scope
dev and test (*)	All query endpoints (GET) (**)	Rate limit at 1 request per second (60 requests per minute) on average	Per client IP address
dev and test (*)	All command endpoints (POST) (**)	Rate limit at 1 request per 2 seconds (30 requests per minute) on average	Per client IP address
All	/listings/create	Rate limit at 100 requests per minute on average, in addition to other applicable limits.	Total in the marketplace environment
All	All (**)	Concurrent requests limited to 10	Per client IP address

(*) For marketplace environments created before 2023-01-31, these rate limits will come into effect on 2023-02-15 at 10:00:00 UTC.

(**) The limit applies globally across all API endpoints, so that all requests in total across all endpoints are subject to the limit.

The rate limiters use a token bucket algorithm and allow for a burst of requests. The rate limiters begin to enforce the stated average rate if the burst capacity is exhausted. The burst capacity accumulates back when the request rate remains below the limit.

The concurrency limiter may allow higher number of concurrent requests at times. However, API clients should limit concurrent requests to 10 or fewer in order to avoid triggering the concurrency limiter.

API requests that are rejected due to a request rate or concurrency limit receive a response with HTTP status code 429. Requests that are rejected due to the concurrency limit will have empty response body. Client implementations must use the HTTP status code to distinguish these responses.

See this article for advice on how to handle these limits gracefully.

Marketplace

API prefix

/v1/integration_api/marketplace/

Example resource

{
  "data": {
    "id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
    "type": "marketplace",
    "attributes": {
      "name": "My Marketplace",
      "description": "My marketplace"
    }
  }
}

{
  data: {
    id: UUID {uuid: "16c6a4b8-88ee-429b-835a-6725206cd08c"},
    type: "marketplace",
    attributes: {
      name: "My Marketplace",
      description: "My marketplace"
    }
  }
}

The marketplace API resource represents the public data about the marketplace.

`marketplace` resource format

Attribute	Description
name	(string) The marketplace name.
description	(string) DEPRECATED: Not in use anymore. New marketplaces will always have `null` value. The marketplace description.

Show marketplace

HTTP request

GET /v1/integration_api/marketplace/show

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/marketplace/show' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.marketplace.show().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
    "type": "marketplace",
    "attributes": {
      "name": "My Marketplace",
      "description": "My marketplace"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "16c6a4b8-88ee-429b-835a-6725206cd08c"},
    type: "marketplace",
    attributes: {
      name: "My Marketplace",
      description: "My marketplace"
    }
  }
}

Get the marketplace details.

Users

API prefix

/v1/integration_api/users/

Example resource

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "identityProviders": [
        {
          "idpId": "facebook",
          "userId": "11223344"
        }
      ],
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-0177"
        },
        "privateData": {
          "newsletter": true
        }
      },
      "permissions": {
        "postListings": "permission/allow",
        "initiateTransactions": "permission/allow",
        "read": "permission/allow"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      identityProviders: [
        {
          idpId: "facebook",
          userId: "11223344"
        }
      ],
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-0177"
        },
        privateData: {
          newsletter: true
        }
      },
      permissions: {
        postListings: "permission/allow",
        initiateTransactions: "permission/allow",
        read: "permission/allow"
      }
    }
  }
}

The user API resource represents public data about marketplace users.

`user` resource format

Attribute	Description
banned	(boolean) DEPRECATED: Flag indicating whether the user is banned.
deleted	(boolean) Flag indicating whether the user is deleted. Deleted users have all other attributes set to `null` or `false`.
state	(string) User's state. See `user` states.
createdAt	(string, timestamp) The date and time the user signed up in ISO 8601 format.
email	(string, case insensitive) The user's email address. The email address acts as username.
emailVerified	(boolean) Flag indicating if the user's email address had been verified.
pendingEmail	(string, nullable) If present, the user is in the process of changing their email and have not yet verified the new (pending) address.
stripeConnected	(boolean) Flag indicating if the user has completed creating a Stripe account.
identityProviders	(array) Identity provider accounts the user is associated with. No sort order is guaranteed. See `user` identity provider.
profile.firstName	(string) User's first name.
profile.lastName	(string) User's last name.
profile.displayName	(string) User's chosen display name. Defaults to first name plus initial of last name.
profile.abbreviatedName	(string) Initials of user's first and last names.
profile.bio	(string, nullable) User's bio.
profile.publicData	(object) User's public data. See Extended data for details.
profile.protectedData	(object) User's protected data. See Extended data for details.
profile.privateData	(object) User's private data. See Extended data for details.
permissions	(object) User's permissions. See permissionSet for details. This attribute reflects the user's provisional permissions, which may be modified by other factors such as global settings. The user's effective permissions can be fetched via the `effectivePermissionSet` relationship.

`user` identity provider

Describes an identity provider user account that is associated with given user.

Attribute	Description
idpId	(string) IdP ID of the identity provider.
userId	(string) User's account ID in the identity provider.

`user` states

A user resource type may be in one of the following states:

State	Description
active	The user is active. The user can perform any action that is not restricted because of permissions or by other mechanism.
pendingApproval	The user is pending operator approval. The user won't be able to publish listings or initiate transactions until they're approved by an operator.
banned	The user is banned from the marketplace. The user doesn't have authenticated access to any of the marketplace API endpoints.

`user` permissionSet

Object containing the permissions for the user. For each permission the possible values are "permission/allow" and "permission/deny".

The permission set can have different values when fetched via the permissions attribute and the effectivePermissionSet relationship. The permissions attribute reflects the user's provisional permissions, which may be modified by other factors such as global settings. The user's final permissions, determined after considering all factors, can be obtained via the effectivePermissionSet relationship.

Attribute	Description
postListings	User's permission to post listings. If the permission is denied for the user, the endpoints `POST /own_listings/create_draft`, `POST /own_listings/publish_draft`, `POST /own_listings/create` and `POST /own_listings/open` of the Marketplace API respond with `403`.
initiateTransactions	User's permission to initiate transactions. If the permission is denied for the user, the endpoint `POST /transactions/initiate` responds with `403`.
read	User's permission to view listings and related data. If the permission is denied for the user, the endpoints `GET /listings/query`, `GET /listings/show`, `GET /users/show`, `GET /timeslots/query`, `GET /reviews/query` and `GET /reviews/show` respond with `403`.

`user` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the user.
profileImage	image	one	(optional) User's profile image, if any.
stripeAccount	stripeAccount	one	(optional) User's Stripe Account, if any.
effectivePermissionSet	permissionSet	one	User's final permissions, determined after considering all factors, including global settings and defaults.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show user

HTTP request

GET /v1/integration_api/users/show

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/users/show?id=3c073fae-6172-4e75-8b92-f560d58cd47c' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var userId = new UUID("3c073fae-6172-4e75-8b92-f560d58cd47c");
integrationSdk.users.show({id: userId}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-0177"
        },
        "privateData": {
          "newsletter": true
        }
      },
      "permissions": {
        "postListings": "permission/allow",
        "initiateTransactions": "permission/allow",
        "read": "permission/allow"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-0177"
        },
        privateData: {
          newsletter: true
        }
      },
      permissions: {
        postListings: "permission/allow",
        initiateTransactions: "permission/allow",
        read: "permission/allow"
      }
    }
  }
}

Get the public details of a single user. You can look up the user by ID or by email address.

Query parameters

Parameter	Description
id	(optional, uuid) The id of the user.
email	(optional, string, case insensitive) The email address of the user.

Query users

HTTP request

GET /v1/integration_api/users/query

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/users/query' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var userId = new UUID("3c073fae-6172-4e75-8b92-f560d58cd47c");
integrationSdk.users.query().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
      "type": "user",
      "attributes": {
        "banned": false,
        "deleted": false,
        "state": "active",
        "createdAt": "2018-04-17T06:54:38.498Z",
        "email": "joe.dunphy@example.com",
        "emailVerified": true,
        "pendingEmail": null,
        "stripeConnected": false,
        "profile": {
          "firstName": "Joe",
          "lastName": "Dunphy",
          "displayName": "Joe D",
          "abbreviatedName": "JD",
          "bio": "Hello, I'm Joe. Some people call me Joe \"Modern\" D.\n\nAnd just so that you wouldn't think that's too short of an introduction, here a bit more about me:\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
          "publicData": {
            "hobbies": [
              "pizza",
              "gym"
            ]
          },
          "protectedData": {
            "phoneNumber": "+1-202-555-0177"
          },
          "privateData": {
            "keyCode": "1234",
            "moarStuff": {
              "stuff": {
                "first": 1,
                "second": 2
              }
            }
          }
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
      type: "user",
      attributes: {
        banned: false,
        deleted: false,
        state: "active",
        createdAt: new Date("2018-03-28T09:12:58.866Z"),
        email: "joe.dunphy@example.com",
        emailVerified: true,
        pendingEmail: null,
        stripeConnected: false,
        profile: {
          firstName: "Joe",
          lastName: "Dunphy",
          displayName: "Joe D",
          abbreviatedName: "JD",
          bio: "Hello, I'm Joe.",
          publicData: {
            age: 27
          },
          protectedData: {
            phoneNumber: "+1-202-555-0177"
          },
          privateData: {
            newsletter: true
          }
        }
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 3,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query all users of a marketplace. Results are sorted by users' createdAt time in descending order (i.e. most recent users are returned first).

Query parameters

Parameter	Description
createdAtStart	(timestamp, optiona) Filter users by `createdAt` time. Only users created on or after the given time are returned. The timestamp must be in ISO 8601 format.
createdAtEnd	(timestamp, optiona) Filter users by `createdAt` time. Only users created before the given time are returned. The timestamp must be in ISO 8601 format.
meta_*	Query users by `metadata` attribute(s). See Extended data filtering below.
priv_*	Query users by `privateData` attribute(s). See Extended data filtering below.
prot_*	Query users by `protectedData` attribute(s). See Extended data filtering below.
pub_*	Query users by `publicData` attribute(s). See Extended data filtering below.
sort	(string) Specify sort criteria. Default is `createdAt` See Controlling sorting of users below.

Extended data filtering

Queries for metadata, privateData, protectedData and publicData attributes can be done only when extended data schema is defined for the attribute. Only top-level extended data attributes may have schema and are queriable, even though the extended data can be deeply nested. The supported schema types and query semantics are given below (use meta_, priv_, prot_ instead of pub_ for queries depending on the type of extended data):

Schema type	Schema cardinality	Query syntax	Description
enum	one	pub_`ATTRIBUTE_KEY`=`VALUE1,[VALUE2[,...]]`	Match users that have any of the given values as the exact value of `ATTRIBUTE_KEY` (i.e. `OR` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`has_all:VALUE1[,VALUE2[,...]]`	Match users that have all given values for the given multi-enum `ATTRIBUTE_KEY` (i.e. `AND` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`VALUE1[,VALUE2[,...]]`	Same as `has_all:`, we use `AND` semantics by default.
enum	many	pub_`ATTRIBUTE_KEY`=`has_any:VALUE1[,VALUE2[,...]]`	Match users that have any of the given values for the multi-enum `ATTRIBUTE_KEY` (i.e. `OR` semantics).
long	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match users that have a value of `ATTRIBUTE_KEY` that is exactly equal to `VALUE`.
long	one	pub_`ATTRIBUTE_KEY`=`START,END`	Match users that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START` and less than `END`.
long	one	pub_`ATTRIBUTE_KEY`=`START,`	Match users that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START`.
long	one	pub_`ATTRIBUTE_KEY`=`,END`	Match users that have a value of `ATTRIBUTE_KEY` that is less than `END`.
boolean	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match users that have a value of `ATTRIBUTE_KEY` that is equal to `VALUE`.

Controlling sorting of users

The users returned by this endpoint are ordered according to the specification given with sort query parameter. The default value is createdAt, i.e. users are ordered by createdAt time in descending order.

The sort query parameter takes the form of comma-separated list of up to 3 attributes. Results are ordered first by the first one, then by the second and third, if given. Sorting can be done by the following attributes:

Attribute	Description
createdAt	Sort by user creation time.
pub_*	Sort by a numeric `publicData` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Users that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.
priv_*	Sort by a numeric `privateData` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Users that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.
prot_*	Sort by a numeric `protectedData` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Users that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.
meta_*	Sort by a numeric `metadata` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Users that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.

The order is descending for each attribute, but can be reversed by prefixing the attribute with a - sign.

Examples:

sort=-createdAt will return users ordered by createdAt in ascending order
sort=meta_rating will return users ordered by metadata rating in descending order
sort=pub_rank,-createdAt will return users ordered first by publicData rank in descending order and then by createdAt in ascending order.

Pagination limits

When extended data filters or non-default sorting is used, this endpoint has a limit on the maximum number of pages that can be accessed when the total number of users that match the query criteria exceeds 10,000. This is indicated in the API response by the presence of paginationLimit key with an integer value in the API response's meta. Use an additional filter to partition the result set and avoid the limitation. For example, a filter in createdAt time, using the createdAtStart and createdAtEnd query parameters, is well suited for this, as the createdAt value for users is immutable. See Pagination for details.

Update user profile

HTTP request

POST /v1/integration_api/users/update_profile

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/users/update_profile?expand=true,include=profileImage' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "61c9dfef-20d8-4a59-aa39-b2de75b4b8f2",
  "firstName": "Alex",
  "profileImageId": "c5b75c21-5b30-40bf-a114-4688c07128ef",
  "protectedData": {
    "phoneNumber": "+1-202-555-4444"
  },
  "privateData": {
    "discoveredServiceVia": "Twitter"
  },
  "metadata": {
    "identityVerified": true
  }
}'

integrationSdk.users.updateProfile({
  id: new UUID("61c9dfef-20d8-4a59-aa39-b2de75b4b8f2"),
  firstName: "Alex",
  profileImageId: new UUID("c5b75c21-5b30-40bf-a114-4688c07128ef"),
  protectedData: {
    phoneNumber: "+1-202-555-4444"
  },
  privateData: {
    discoveredServiceVia: "Twitter"
  },
  metadata: {
    identityVerified: true
  }
}, {
  expand: true,
  include: ["profileImage"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": false,
      "pendingEmail": null,
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "profile": {
        "firstName": "Alex",
        "lastName": "Dunphy",
        "displayName": "Alex D",
        "abbreviatedName": "AD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-4444"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {
          "identityVerified": true
        }
      },
      "relationships": {
        "profileImage": {
          "data": {
            "id": "c5b75c21-5b30-40bf-a114-4688c07128ef",
            "type": "image"
          }
        }
      }
    }
  },
  "included": [{
    "id": "c5b75c21-5b30-40bf-a114-4688c07128ef",
    "type": "image",
    "attributes": {
      "variants": {
        "default": {
          "width": 750,
          "height": 750,
          "url": "https://www.example.com/image/c5b75c21-5b30-40bf-a114-4688c07128ef"
        }
      }
    }
  }]
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: false,
      pendingEmail: null,
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      profile: {
        firstName: "Alex",
        lastName: "Dunphy",
        displayName: "Alex D",
        abbreviatedName: "AD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-4444"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {
          identityVerified: true
        }
      },
      relationships: {
        profileImage: {
          data: {
            id: UUID {uuid: "c5b75c21-5b30-40bf-a114-4688c07128ef"},
            type: "image"
          }
        }
      }
    }
  },
  included: [{
    id: UUID {uuid: "c5b75c21-5b30-40bf-a114-4688c07128ef"},
    type: "image",
    attributes: {
      variants: {
        default: {
          width: 750,
          height: 750,
          url: "https://www.example.com/image/c5b75c21-5b30-40bf-a114-4688c07128ef",
        }
      }
    }
  }]
}

Command that updates the given user's profile information.

Body parameters

Parameter	Description
id	(uuid) The ID of the user that is being updated.
firstName	(string, optional) User's first name. Can not be empty string.
lastName	(string, optional) User's last name. Can not be empty string.
displayName	(string, optional) User's chosen display name. Passing `null` or `""` here will reset the display name to the default formed by user's first name plus initial of last name.
bio	(string, optional) User's bio. Passing `null` here will remove bio. Can be up to 5000 characters.
publicData	(object, optional) User's public data. See Extended data. The total size of the public data object as JSON string must not exceed 50KB. The given `publicData` object is merged with the existing user `publicData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the users's `publicData`.
protectedData	(object, optional) User's protected data. See Extended data. The total size of the protected data object as JSON string must not exceed 50KB. The given `protectedData` object is merged with the existing user `protectedData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the users's `protectedData`.
privateData	(object, optional) User's private data. See Extended data. The total size of the private data object as JSON string must not exceed 50KB. The given `privateData` object is merged with the existing user `privateData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the users's `privateData`.
metadata	(object, optional) User's public metadata. See Extended data. The total size of the metadata object as JSON string must not exceed 50KB. The given `metadata` object is merged with the existing user `metadata` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the users's `metadata`.
profileImageId	(uuid, optional) Set the user's profile image. The ID must be of an image previously uploaded via the `/images/upload` API endpoint. Earlier profile image is deleted. If the value is set to `null`, the current profile image (if any) will be removed.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
409	image-invalid	Given image is not found or is already in use. Upload a new image.

Approve user

HTTP request

POST /v1/integration_api/users/approve

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/users/approve?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "3c073fae-6172-4e75-8b92-f560d58cd47c"}'

integrationSdk.users.approve({
  id: new UUID("3c073fae-6172-4e75-8b92-f560d58cd47c")
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-0177"
        },
        "privateData": {
          "newsletter": true
        }
      },
      "permissions": {
        "postListings": "permission/allow",
        "initiateTransactions": "permission/allow",
        "read": "permission/allow"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-0177"
        },
        privateData: {
          newsletter: true
        }
      },
      permissions: {
        postListings: "permission/allow",
        initiateTransactions: "permission/allow",
        read: "permission/allow"
      }
    }
  }
}

Command for approving a user that is currently in pendingApproval state. The user's state is set to active.

Body parameters

Parameter	Description
id	(uuid) The user ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Update permissions

HTTP request

POST /v1/integration_api/users/update_permissions

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/users/update_permissions?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "61c9dfef-20d8-4a59-aa39-b2de75b4b8f2",
  "postListings": "permission/allow",
  "initiateTransactions": "permission/deny"
}'

integrationSdk.users.updatePermissions({
  id: new UUID("61c9dfef-20d8-4a59-aa39-b2de75b4b8f2"),
  "postListings": "permission/allow",
  "initiateTransactions": "permission/deny"
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-0177"
        },
        "privateData": {
          "newsletter": true
        }
      },
      "permissions": {
        "postListings": "permission/allow",
        "initiateTransactions": "permission/deny",
        "read": "permission/allow"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-0177"
        },
        privateData: {
          newsletter: true
        }
      },
      permissions: {
        postListings: "permission/allow",
        initiateTransactions: "permission/deny",
        read: "permission/allow"
      }
    }
  }
}

Command for updating user's permissions.

Body parameters

Parameter	Description
id	(uuid) The user ID.
postListings	(string, optional) Either `"permission/allow"` or `"permission/deny"`
initiateTransactions	(string, optional) Either `"permission/allow"` or `"permission/deny"`
read	(string, optional) Either `"permission/allow"` or `"permission/deny"`

The request body must include the id parameter (required) and can optionally include one or more permissions where the key is a permission name (e.g., postListings) and the value is either "permission/allow" or "permission/deny". You can refer to the complete list of available permissions in the permissionSet.

Permissions not included in the request will remain unchanged.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Stripe Account

API prefix

/v1/integration_api/stripe_account/

Example resource

{
  "data": {
    "id": "cb5e8305-67f0-4d04-a081-954411eaf6b9",
    "type": "stripeAccount",
    "attributes": {
      "stripeAccountId": "acct_1EHoPgDktN4RYwdG"
    }
  }
}

{
  data: {
    id: UUID {uuid: "cb5e8305-67f0-4d04-a081-954411eaf6b9"},
    type: "stripeAccount",
    attributes: {
      stripeAccountId: "acct_1EHoPgDktN4RYwdG"
    }
  }
}

The stripeAccount resource type represents details about the Stripe account of a user.

Stripe Accounts are currently accessible only via the stripeAccount relationship of user resources.

`stripeAccount` resource format

Attribute	Description
stripeAccountId	(string) Stripe's own ID for the Stripe Account.

Listings

API prefix

/v1/integration_api/listings/

Example resource

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day",
        "entries": [
          {
            "dayOfWeek": "mon",
            "seats": 1
          },
          {
            "dayOfWeek": "tue",
            "seats": 0
          },
          {
            "dayOfWeek": "fri",
            "seats": 4
          }
        ]
      },
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 1
          },
          {
            dayOfWeek: "tue",
            seats: 0
          },
          {
            dayOfWeek: "fri",
            seats: 7
          }
        ]
      },
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

The listing API resource type represents public information about listings in the marketplace.

`listing` resource format

Attribute	Description
title	(string) Listing's title.
description	(string) Listing's description.
geolocation	(object, location) Latitude (`lat`) and longitude (`lng`) of the listing's location.
createdAt	(string, timestamp) The date and time when the listing was created in ISO 8601 format.
price	(object, money) Listing's unit price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD).
availabilityPlan	(object) Listing's availability plan. See `listing` availability plan.
publicData	(object) Listing's public data. See Extended data.
privateData	(object) Listing's private data. See Extended data.
metadata	(object) Listing's public metadata. See Extended data.
state	(string) The listing's current state. See Listing states.
deleted	(boolean) Flag indicating whether the listing has been deleted. If `true`, all other attributes of the listing will be returned as default values (`false` for booleans and `null` for all else).

`listing` states

A listing resource type may be in one of the following states:

State	Description
draft	Listing is in draft state and has not been published yet. Listings that are in draft state are never returned by the public `/listings` queries in the Marketplace API.
pendingApproval	Listing is pending operator approval. Newly created listings have this state, when the marketplace has the listing approval feature enabled. Listings that are pending approval are never returned by the public `/listings` queries in the Marketplace API.
published	Listing is published and discoverable via the `/listings/query` endpoint of the Marketplace API.
closed	A published listing can be closed by its author or a marketplace operator. Closed listings are not returned in search results or public listing queries in the Marketplace API and new transactions can not be initiated with them, but they can still be accessed as own listings or via the listing ID, or when related to another known resource (such as `transaction`). The intention of closing a listing is not to delete it, but to stop advertising it. A closed listing can be reopened, which sets it in `published` state again.

`listing` availability plan

The listing resource's availabilityPlan attribute contains the type and, in case of time-based availability plans, the timezone of the listing's availability plan.

Attribute	Description
type	(string) Availability plan type. Possible types are `availability-plan/day` for day-based availability and `availability-plan/time` for time-based availability.
timezone	(string) Only for the `availability-plan/time` type. Time zone in which the plan is set. Supports time zone names from the TZ time zone database, for example "Europe/Berlin". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
entries	(array) List of zero or more availability entries for the plan.
entries.*.dayOfWeek	(string) An abbreviated day of week: `mon`, `tue`, `wed`, `thu`, `fri`, `sat` or `sun`.
entries.*.seats	(number) An integer number of available seats for the given day of week. The number of seats indicate how many times a given date can be booked. Setting `seats` to 0 means that the entry is unavailable for bookings.
entries.*.startTime	(string) Only for the `availability-plan/time` type. Start time for the availability slot in hh:mm format so that the number of minutes is a multiple of 5.
entries.*.endTime	(string) Only for the `availability-plan/time` type. End time for the availability slot in hh:mm format so that the number of minutes is a multiple of 5. 00:00 can be used to express midnight.

Listings without an availability plan are interpreted to have a day-based plan with 1 seat available for each day of the week.

Passing null as an availability plan will make the listing default to daily availability plan with 1 seat. To make the listing unavailable, pass availability plan with 0 seats.

`listing` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the user.
author	user	one	The marketplace user, to whom the listing belongs. Supported nested relationships: `author.profileImage`.
images	image	many	(optional) The ordered list of listing images, if any.
currentStock	stock	one	(optional) The listing's currently available stock, if set.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show listing

HTTP request

GET /v1/integration_api/listings/show

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");
integrationSdk.listings.show({id: listingId}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day",
        "entries": [
          {
            "dayOfWeek": "mon",
            "seats": 3
          },
          {
            "dayOfWeek": "fri",
            "seats": 1
          }
        ]
      },
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 3
          },
          {
            dayOfWeek: "fri",
            seats: 1
          }
        ]
      },
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Query the details of a given listing.

Query parameters

Parameter	Description
id	The ID of the listing.

Query listings

HTTP request

GET /v1/integration_api/listings/query

Example request

# Search all listings, ordered by distance from given location,
# matching only listings with `publicData.gears` less than 23
# and price amount between 14.00 and 16.00.
$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/listings/query?origin=40.00,-74.00&price=1400,1600&pub_gears=,23' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Search all listings, ordered by distance from given location,
// matching only listings with `publicData.gears` less than 23
// and price amount between 14.00 and 16.00.
var origin = new LatLng(40.0, -74.0);
integrationSdk.listings.query({
  origin: origin,
  price: "1400,1600",
  pub_gears: ",23"
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
      "type": "listing",
      "attributes": {
        "description": "7-speed Hybrid",
        "deleted": false,
        "geolocation": {
          "lat": 40.64542,
          "lng": -74.08508
        },
        "createdAt": "2018-03-23T08:40:24.443Z",
        "state": "published",
        "title": "Peugeot eT101",
        "availabilityPlan": {
          "type": "availability-plan/day",
          "entries": [
            {
              "dayOfWeek": "mon",
              "seats": 3
            },
            {
              "dayOfWeek": "fri",
              "seats": 1
            }
          ]
        },
        "privateData": {
          "externalServiceId": "abcd-service-id-1234"
        },
        "publicData": {
          "address": {
            "city": "New York",
            "country": "USA",
            "state": "NY",
            "street": "230 Hamilton Ave"
          },
          "category": "road",
          "gears": 22,
          "rules": "This is a nice, bike! Please, be careful with it."
        },
        "metadata": {
          "promoted": true
        },
        "price": {
          "amount": 1590,
          "currency": "USD"
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 1014,
    "totalPages": 11,
    "page": 1,
    "perPage": 100
  }
}

{
  data: [
    {
      id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
      type: "listing",
      attributes: {
        description: "7-speed Hybrid",
        deleted: false,
        geolocation: LatLng {lat: 40.64542, lng: -74.08508},
        createdAt: new Date("2018-03-23T08:40:24.443Z"),
        state: "published",
        title: "Peugeot eT101",
        availabilityPlan: {
          type: "availability-plan/day",
          entries: [
            {
              dayOfWeek: "mon",
              seats: 3
            },
            {
              dayOfWeek: "fri",
              seats: 1
            }
          ]
        },
        privateData: {
          externalServiceId: "abcd-service-id-1234"
        },
        publicData: {
          address: {
            city: "New York",
            country: "USA",
            state: "NY",
            street: "230 Hamilton Ave"
          },
          category: "road",
          gears: 22,
          rules: "This is a nice, bike! Please, be careful with it."
        },
        metadata: {
          promoted: true
        },
        price: Money {amount: 1590, currency: "USD"}
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 1014,
    totalPages: 11,
    page: 1,
    perPage: 100
  }
}

Query all marketplace listings. Returns 0 or more results.

This query returns listings in all possible states by default. Use the states query parameter to narrow down the query, where necessary.

Query parameters

Parameter	Description
authorId	(uuid, optional) Match only listings belonging to given user ID.
ids	(comma separated list of uuids, optional) List of uuids. Match only listings with an ID contained in the given list. A maximum of 100 IDs can be given.
states	(comma separated list of strings, optional) List of one or more states to filter the results by. Only listings in one of the given states are returned.
createdAtStart	(timestamp, optiona) Filter listings by `createdAt` time. Only listings created on or after the given time are returned. The timestamp must be in ISO 8601 format.
createdAtEnd	(timestamp, optiona) Filter listings by `createdAt` time. Only listings created before the given time are returned. The timestamp must be in ISO 8601 format.
keywords	(string, optional) Narrow down and sort search results based on given keywords. The keywords are matched against listing title, description and optionally also specific `publidData` fields with type `text` defined in the listing public data schema of a marketplace. Can not be combined with the `origin` parameter.
origin	(coordinates, optional) Search listings, based on given location. The location is given as comma-separated tuple of latitude and longitude values (e.g. `40.12,-70.3345`). The listings in the query result are sorted by distance from the given origin. Can not be combined with the `keywords` parameter.
bounds	(bounding box coordinates, optional) Match only listings within a bounding box. The bounding box is given as comma-separated list of four coordinate values: NE lat, NE, lng, SW lat and SW lng. E.g. `43.0,-73.0,40.0,-77.0`.
price	(integer or integer range) Match only listings with price amount within given range. The amounts must be given as integers in the currency's minor unit (e.g. cents for USD). The currency of the listing price has no effect on the query. See Price filtering below for range syntax.
start	(timestamp) Start time of the availability interval to match listings against in ISO 8601 format. The start time must be between one day in the past and 365 days in the future. If omitted, the listings' availability data is ignored in the query. See Availability filtering below.
end	(timestamp) End time of the availability interval to match listings against (exclusive) in ISO 8601 format. The end time must be after the `start` time and must be at most 365 days in the future or at most 90 days from the `start` time (whichever comes sooner). See Availability filtering below.
seats	(integer) The number of seats a listing must have available at minimum on the given interval to to match the search criteria. See Availability filtering below. Default value is `1`.
availability	(string) The type of availability search. Accepts values: `day-full`, `day-partial`, `time-full` or `time-partial`. Default value is: `day-full`. DEPRECATED values `full` and `partial` are equivalent to `day-full` and `day-partial`, respectively. See Availability filtering below.
minDuration	(integer) Match only listings with an availability interval of at least this duration within the query range specified by `start` and `end`. Only supported when `availability` is set to either `day-partial` and `time-partial`. For `day-partial` queries, the value of `minDuration` is in days. For `time-partial` queries, the value of `minDuration` is in minutes. Default value is `0`, i.e. any duration of availability matches.
stockMode	(string) The type of stock query. Control whether listing queries using `minStock` match listings without any defined stock. The value must be one of `strict` (the default) or `match-undefined`. If `strict`, only listings that have explicitly defined stock quantity will match. If `match-undefined`, the query will also match listings without any set stock.
minStock	(integer) Match only listings that have current stock quantity equal to or greater than the given integer number. If `stockMode` is set to `match-undefined`, the query will also match any listings without a defined stock quantity.
pub_*	Query listings by `publicData` attribute(s). See Extended data filtering below.
meta_*	Query listings by `metadata` attribute(s). See Extended data filtering below.
sort	(string) Specify sort criteria. Can not be used in combination with the `origin` query parameter. Default is `createdAt` See Controlling sorting of listings below.

Price filtering

price range can be specified as:

Query syntax	Description
`price=VALUE`	Match listings that have price amount exactly equal to `VALUE`.
`price=START,END`	Match listings that have price amount greater than or equal to `START` and less than `END`.
`price=START,`	Match listings that have price amount greater than or equal to `START`.
`price=,END`	Match listings that have price amount less than `END`.

Extended data filtering

Queries for publicData and metadata attributes can be done only when extended data schema is defined for the attribute. Only top-level extended data attributes may have schema and are queriable, even though the extended data can be deeply nested. The supported schema types and query semantics are given below (use meta_ instead of pub_ for queries based on metadata):

Schema type	Schema cardinality	Query syntax	Description
enum	one	pub_`ATTRIBUTE_KEY`=`VALUE1,[VALUE2[,...]]`	Match listings that have any of the given values as the exact value of `ATTRIBUTE_KEY` (i.e. `OR` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`has_all:VALUE1[,VALUE2[,...]]`	Match listings that have all given values for the given multi-enum `ATTRIBUTE_KEY` (i.e. `AND` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`VALUE1[,VALUE2[,...]]`	Same as `has_all:`, we use `AND` semantics by default.
enum	many	pub_`ATTRIBUTE_KEY`=`has_any:VALUE1[,VALUE2[,...]]`	Match listings that have any of the given values for the multi-enum `ATTRIBUTE_KEY` (i.e. `OR` semantics).
long	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match listings that have a value of `ATTRIBUTE_KEY` that is exactly equal to `VALUE`.
long	one	pub_`ATTRIBUTE_KEY`=`START,END`	Match listings that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START` and less than `END`.
long	one	pub_`ATTRIBUTE_KEY`=`START,`	Match listings that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START`.
long	one	pub_`ATTRIBUTE_KEY`=`,END`	Match listings that have a value of `ATTRIBUTE_KEY` that is less than `END`.
boolean	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match listings that have a value of `ATTRIBUTE_KEY` that is equal to `VALUE`.
text	one	keywords=`KEYWORDS`	Match and sort listings that have a string from `KEYWORDS` in listing title, description or extended data attributes with type `text`.

Availability filtering

The availability filtering is controlled by the following query parameters: start, end, availability, seats and minDuration. The following rules apply:

Only listings in the published state match availability queries.
When availability is set to either day-full or day-partial, only listings with a day-based availability plan are matched.
When availability is set to time-full or time-partial, only listings with time-based availability plans are matched.
day-full and time-full availability queries match only listings that have availability with the required number of seats for the entire duration of the query range (specified by start and end).
day-partial and time-partial availability queries match only listings that have some availability with the required number of seats and minDuration for the given query range (specified by start and end). minDuration must be given in integer number of days (for day-partial) or minutes (for time-partial).

Pagination is NOT supported for time-based availability filtering, or when day-based filtering is used in combination with minDuration.

Pagination is not supported in the following cases:

time-full or time-partial queries
day-partial queries using minDuration

In those cases, the query returns up to 100 results (subject to the perPage query parameter), and use of page for accessing further results is not supported. In order to make sure you get the most relevant query results, adjust you query criteria and use sorting.

Controlling sorting of listings

The query results are ordered subject to the following rules:

When keywords parameter is used and sort parameter is not defined, listings are ordered by relevance score in descending order (i.e. most relevant listings first).
When origin parameter is used, listings are ordered by distance from the given origin location in ascending order.
Otherwise, listings are ordered according to the specification given with sort query parameter. The default value is createdAt, i.e. listings are ordered by createdAt time in descending order.

Attribute	Description
createdAt	Sort by listing creation time.
price	Sort by listing's price amount (only considers the numeric value of the price, ignoring currency, i.e. no currency conversion is performed).
pub_*	Sort by a numeric `publicData` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Listings that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.
meta_*	Sort by a numeric `metadata` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Listings that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.

The order is descending for each attribute, but can be reversed by prefixing the attribute with a - sign.

Examples:

sort=-createdAt will return listings ordered by createdAt in ascending order
sort=meta_rating will return listings ordered by metadata rating in descending order
sort=pub_gears,-price will return listings ordered first by publicData gears in descending order and then by price amount in ascending order.

Pagination limits

When pagination is supported, this endpoint has a limit on the maximum number of pages that can be accessed when the total number of listings that match the query criteria exceeds 10,000. This is indicated in the API response by the presence of paginationLimit key with an integer value in the API response's meta. Use an additional filter to partition the result set and avoid the limitation. For example, a filter in createdAt time, using the createdAtStart and createdAtEnd query parameters, is well suited for this, as the createdAt value for listings is immutable. See Pagination for details.

Create listing

HTTP request

POST /v1/integration_api/listings/create

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/listings/create?expand=true,include=images' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "title": "Very good item",
  "authorId": "7966463a-1b15-4931-b056-27a546dd12bb",
  "state": "published",
  "description": "Brand new track bike.",
  "geolocation": {
    "lat": 40.64542,
    "lng": -74.08508
  },
  "privateData": {
    "externalServiceId": "new-service-id-4324"
  },
  "publicData": {
    "address": {"country": "USA"}
    "category": "track",
    "gears": 22
  },
  "metadata": {
    "verified": true,
    "promoted": false,
    "rating": 4
  },
  "images": [
    "f8afadaa-dd4f-4536-b9a7-b405834dc25d"
  ]
}'

integrationSdk.listings.create({
  title: "Very good item",
  authorId: new UUID("7966463a-1b15-4931-b056-27a546dd12bb"),
  state: "published",
  description: "Brand new track bike.",
  geolocation: new LatLng(40.64542, -74.08508),
  privateData: {
    externalServiceId: "new-service-id-4324"
  },
  publicData: {
    address: {
      country: "USA"
    },
    category: "track",
    gears: 22
  },
  metadata: {
    verified: true,
    promoted: false,
    rating: 4
  },
  images: [
    new UUID("f8afadaa-dd4f-4536-b9a7-b405834dc25d")
  ]
}, {
  expand: true,
  include: ["images"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "Brand new track bike.",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "new-service-id-4324"
      },
      "publicData": {
        "address": {
          "country": "USA"
        },
        "category": "track",
        "gears": 22
      },
      "metadata": {
        "promoted": false,
        "verified": true,
        "rating": 4
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    },
    "relationships": {
      "images": {
        "data": [
          {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "Brand new track bike.",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "new-service-id-4324"
      },
      publicData: {
        address: {
          country: "USA"
        },
        category: "track",
        gears: 22
      },
      metadata: {
        promoted: false,
        verified: true,
        rating: 4
      },
      price: Money {amount: 1590, currency: "USD"}
    },
    relationships: {
      images: {
        data: [
          {id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"}, type: "image"}
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    }
  ]
}

Command for creating a listing.

Body parameters

Parameter	Description
title	(string) Listing's title. Must be between 1 and 1000 characters.
authorId	(uuid) The ID of the marketplace user to whom the listing belongs.
state	(string) The state of the listing that is being created. Allowed values are one of 'published' or 'pendingApproval'.
description	(string, optional) Listing's description. Must be between 1 and 5000 characters.
geolocation	(object, optional) Latitude (`lat`) and longitude (`lng`) of the listing's location.
price	(object, optional) Listing's price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD).
availabilityPlan	(object, optional) Listing's availability plan. See `listing` availability plan for the object format.
publicData	(object, optional) Listing's public data. See Extended data. The total size of the public data object as JSON string must not exceed 50KB.
privateData	(object, optional) Listing's private data. See Extended data. The total size of the private data object as JSON string must not exceed 50KB.
metadata	(object, optional) Listing's public metadata. See Extended data. The total size of the metadata object as JSON string must not exceed 50KB.
images	(array, optional) List of image IDs for the listing. The listing's images will be set to the exact given list. See also `/images/upload`.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	Trusted token is not provided.
409	user-is-banned	The user whose ID matches with `authorId` is banned
409	user-pending-approval	The user whose ID matches with `authorId` is pending approval
409	user-not-found	`authorId` did not match with any user
429	too-many-requests	Rate limit is reached. Try again after some time.

Update listing

HTTP request

POST /v1/integration_api/listings/update

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/listings/update?expand=true,include=images' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "description": "Brand new track bike.",
  "privateData": {
    "externalServiceId": "new-service-id-4324"
  },
  "publicData": {
    "address": {"country": "USA"}
    "category": "track",
    "rules": null
  },
  "metadata": {
    "verified": true,
    "promoted": false,
    "rating": 4
  },
  "images": [
    "f8afadaa-dd4f-4536-b9a7-b405834dc25d"
  ]
}'

integrationSdk.listings.update({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  description: "Brand new track bike.",
  privateData: {
    externalServiceId: "new-service-id-4324"
  },
  publicData: {
    address: {
      country: "USA"
    },
    category: "track",
    rules: null
  },
  metadata: {
    verified: true,
    promoted: false,
    rating: 4
  },
  images: [
    new UUID("f8afadaa-dd4f-4536-b9a7-b405834dc25d")
  ]
}, {
  expand: true,
  include: ["images"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "Brand new track bike.",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "new-service-id-4324"
      },
      "publicData": {
        "address": {
          "country": "USA"
        },
        "category": "track",
        "gears": 22
      },
      "metadata": {
        "promoted": false,
        "verified": true,
        "rating": 4
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    },
    "relationships": {
      "images": {
        "data": [
          {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "Brand new track bike.",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "new-service-id-4324"
      },
      publicData: {
        address: {
          country: "USA"
        },
        category: "track",
        gears: 22
      },
      metadata: {
        promoted: false,
        verified: true,
        rating: 4
      },
      price: Money {amount: 1590, currency: "USD"}
    },
    relationships: {
      images: {
        data: [
          {id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"}, type: "image"}
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    }
  ]
}

Command for updating listing details. Cannot be used to change listing state.

Body parameters

Parameter	Description
id	(uuid) The ID of the listing that is being updated.
title	(string, optional) Listing's title. Must be between 1 and 1000 characters.
description	(string, optional) Listing's description. Must be between 1 and 5000 characters.
geolocation	(object, optional) Latitude (`lat`) and longitude (`lng`) of the listing's location. Pass `null` to remove the location data from the listing.
price	(object, optional) Listing's price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD). Pass `null` to remove the price from the listing.
availabilityPlan	(object, optional) Listing's availability plan. See `listing` availability plan for the object format. The availability plan must be specified in full, partial updates are not supported. Passing `null` as an availability plan will make the listing default to daily availability plan with 1 seat. To make the listing unavailable, pass availability plan with 0 seats.
publicData	(object, optional) Listing's public data. See Extended data. The total size of the public data object as JSON string must not exceed 50KB. The given `publicData` object is merged with the existing listing `publicData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the listing's `publicData`.
privateData	(object, optional) Listing's private data. See Extended data. The total size of the private data object as JSON string must not exceed 50KB. The given `privateData` object is merged with the existing listing `privateData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the listing's `privateData`.
metadata	(object, optional) Listing's public metadata. See Extended data. The total size of the metadata object as JSON string must not exceed 50KB. The given `metadata` object is merged with the existing listing `metadata` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the listing's `metadata`.
images	(array, optional) List of image IDs for the listing. The listing's images will be set to the exact given list, i.e. new images are added to the listing, listing images that are not given are deleted and order is set as given. See also `/images/upload`.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Close listing

HTTP request

POST /v1/integration_api/listings/close

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/listings/close?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}'

integrationSdk.listings.close({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f")
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "closed",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "closed",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Command for closing a listing. The listing's state is set to closed. When a listing is closed, it is not anymore discoverable via the public Marketplace API /listings/query endpoint, but can be found by ID or through other related resources (e.g. transaction). See Concepts for details.

Note that the Integration API's /listings/query returns all listings by default, including closed ones.

Body parameters

Parameter	Description
id	(uuid) The listing ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Open listing

HTTP request

POST /v1/integration_api/listings/open

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/listings/open?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}'

integrationSdk.listings.open({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f")
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Command for opening a closed listing. The listing's state is set to published.

Body parameters

Parameter	Description
id	(uuid) The listing ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Approve listing

HTTP request

POST /v1/integration_api/listings/approve

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/listings/approve?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}'

integrationSdk.listings.approve({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f")
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Command for approving a listing that is currently in pendingApproval state. The listing's state is set to published.

Body parameters

Parameter	Description
id	(uuid) The listing ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Availability exceptions

API prefix

/v1/integration_api/availability_exceptions/

Example resource

{
  "data": {
    "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e",
    "type": "availabilityException",
    "attributes": {
      "seats": 1,
      "start": "2018-11-26T00:00:00.000Z",
      "end": "2018-11-28T00:00:00.000Z"
    }
  }
}

{
  data: {
    id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
    type: "availabilityException",
    attributes: {
      seats: 1,
      start: new Date("2018-11-26T00:00:00.000Z"),
      end: new Date("2018-11-28T00:00:00.000Z")
    }
  }
}

The availabilityException API resource type represents information about a single availability exception. Availability exceptions are always linked to a particular listing and serve to override the listing's availability plan for a given time range. See also Listing availability management.

`availabilityException` resource format

Attribute	Description
seats	(number) An integer number of available seats for the exception. Setting `seats` to 0 means that the listing is unavailable.
start	(string, timestamp) The date and time when the availability exception starts. Specified in ISO 8601 format.
end	(string, timestamp) The date and time (exclusive) when the availability exception ends. Specified in ISO 8601 format.

`availabilityException` relationships

Relationship	Resource type	Cardinality	Description
listing	listing	one	The listing to which the availability exception applies.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Query availability exceptions

HTTP request

GET /v1/integration_api/availability_exceptions/query

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/availability_exceptions/query?listingId=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&start=2018-11-27T00:00:00.000Z&end=2018-12-30T00:00:00.000Z' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.availabilityExceptions.query({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2018-11-27T00:00:00.000Z"),
  end: new Date("2018-12-30T00:00:00.000Z")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e",
      "type": "availabilityException",
      "attributes": {
        "seats": 1,
        "start": "2018-11-26T00:00:00.000Z",
        "end": "2018-11-28T00:00:00.000Z"
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
      type: "availabilityException",
      attributes: {
        seats: 1,
        start: new Date("2018-11-26T00:00:00.000Z"),
        end: new Date("2018-11-28T00:00:00.000Z")
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 5,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query that returns all the availability exceptions for a given listing and time range.

Query parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
start	(timestamp) The start date and time for the query range in ISO 8601 format. The start time must be between 366 days in the past and 366 days in the future.
end	(timestamp) The end date and time for the query range in ISO 8601 format. The end time must be after the `start` time and must be at most 366 days in the future and at most 90 days after the `start` time.

Create availability exceptions

HTTP request

POST /v1/integration_api/availability_exceptions/create

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/availability_exceptions/create?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "start": "2018-11-26T00:00:00.000Z",
  "end": "2018-11-28T00:00:00.000Z",
  "seats": 1
}'

integrationSdk.availabilityExceptions.create({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2018-11-26T00:00:00.000Z"),
  end: new Date("2018-11-28T00:00:00.000Z"),
  seats: 3
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response shell { "data": { "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e", "type": "availabilityException", "attributes": { "seats": 3, "start": "2018-11-26T00:00:00.000Z", "end": "2018-11-28T00:00:00.000Z" } } }

// res.data
{
  data: {
    id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
    type: "availabilityException",
    attributes: {
      seats: 3,
      start: new Date("2018-11-26T00:00:00.000Z"),
      end: new Date("2018-11-28T00:00:00.000Z")
    }
  }
}

Create a new availability exception for a given listing. You can not create availability exceptions with overlapping time ranges.

Body parameters

Parameter	Description
seats	(number) Integer number of available seats.
start	(string, timestamp) The date and time when the availability exception starts. Specified in ISO 8601 format. The availability exception start time must be at most 365 days in the future.
end	(string, timestamp) The date and time (exclusive) when the availability exception ends. Specified in ISO 8601 format. The availability exception end time must be at most 365 days in the future.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Both start and end time minutes must be multiple of 5 and seconds and milliseconds must be 0. For example:

valid: 2018-11-26T02:00:00.000Z
invalid: 2018-11-26T00:02:30.000Z

Delete availability exceptions

HTTP request

POST /v1/integration_api/availability_exceptions/delete

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/availability_exceptions/delete' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e"
}'

integrationSdk.availabilityExceptions.delete({
  id: new UUID("34cf5423-04ee-42c7-8786-2e206ef34a9e")
}, {
  expand: false
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e",
    "type": "availabilityException"
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
    type: "availabilityException"
  }
}

Command for deleting an availability exception with a given ID.

Body parameters

Parameter	Description
id	(uuid) The availability exception ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Images

API prefix

/v1/integration_api/images

Example resource

{
  "data": {
    "id": "5a8f34f6-202c-4916-af7a-53d56004e872",
    "type": "image",
    "attributes": {
      "variants": {
        "default": {
          "name": "default",
          "width": 720,
          "height": 540,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        },
        "landscape-crop": {
          "name": "landscape-crop",
          "width": 800,
          "height": 600,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop"
        },
        "landscape-crop2x": {
          "name": "landscape-crop2x",
          "width": 1600,
          "height": 1200,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop2x"
        }
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "5a8f34f6-202c-4916-af7a-53d56004e872"},
    type: "image",
    attributes: {
      variants: {
        default: {
          name: "default",
          width: 720,
          height: 540,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        },
        "landscape-crop": {
          name: "landscape-crop",
          width: 800,
          height: 600,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop"
        },
        "landscape-crop2x": {
          name: "landscape-crop2x",
          width: 1600,
          height: 1200,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop2x"
        }
      }
    }
  }
}

The image resource represents user profile and listing images. Images can only be uploaded as JPG, PNG, or non-animated GIF.

`image` resource format

Attribute	Description
variants	(object) Object containing image variant information. Keys are variant names and values are objects representing the variant.
variants.*.width	(number) The actual width of the image in pixels after the transformation corresponding to the variant.
variants.*.height	(number) The actual height of the image in pixels after the transformation corresponding to the variant.
variants.*.url	(string) The public URL for the image variant. Always use the returned URL exactly as returned by the API. Do not attempt to manually construct an image URL.
variants.*.name	(string) The variant name. Same as the key.

Image variants

An example request that fetches a listing with two image variants: a predefined one and a custom one that is defined in the request.

$ curl 'https://flex-integ-api.sharetribe.com/v1/api/listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&include=images&fields.image=variants.square-small,variants.my-variant&imageVariant.my-variant=w:320;h:640;fit:scale' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

const sdkUtil = sharetribeIntegrationSdk.util;
var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");

integrationSdk.listings.show({
  id: listingId,
  include: ["images"],
  "fields.image": ["variants.square-small", "variants.my-variant"],
  // SDK provides a util function to construct image variant URL param strings
  "imageVariant.my-variant": sdkUtil.objectQueryString({
    w: 320,
    h: 640,
    fit: 'scale'
  })
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {...},
    "relationships": {
      "images": {
        "data": [
          {
            "id": "4617c584-edfd-49e9-be43-2f1d50fb6e35",
            "type": "image"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "4617c584-edfd-49e9-be43-2f1d50fb6e35",
      "type": "image",
      "attributes": {
        "variants": {
          "my-variant": {
            "height": 640,
            "width": 320,
            "url": "https://www.example.com/image/5f2a6d44-c826-4a20-aae8-4c24b80b8dc6",
            "name": "my-variant"
          },
          "square-small": {
            "height": 240,
            "width": 240,
            "url": "https://www.example.com/image/5f2a6d65-28fe-49c5-9218-8c6a3924349a",
            "name": "square-small"
          }
        }
      }
    }
  ]
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {...},
    relationships: {
      images: {
        data: [
          {
            id: UUID {uuid: "4617c584-edfd-49e9-be43-2f1d50fb6e35"},
            type: "image"
          }
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "4617c584-edfd-49e9-be43-2f1d50fb6e35"},
      type: "image",
      attributes: {
        variants: {
          "my-variant": {
            height: 640,
            width: 320,
            url: "https://www.example.com/image/5f2a6d44-c826-4a20-aae8-4c24b80b8dc6",
            name: "my-variant"
          },
          "square-small": {
            height: 240,
            width: 240,
            url: "https://www.example.com/image/5f2a6d65-28fe-49c5-9218-8c6a3924349a",
            name: "square-small"
          }
        }
      }
    }
  ]
}

Unlike other resource attributes, variants other than default need to be explicitly requested via Sparse attributes query.

Predefined image variants

The following image variants are available for profile and listing images:

Variant	Fit mode	Width	Height
default	scale	750px	750px
landscape-crop	crop	400px	267px
landscape-crop2x	crop	800px	533px
landscape-crop4x	crop	1600px	1066px
landscape-crop6x	crop	2400px	1602px
scaled-small	scale	320px	320px
scaled-medium	scale	750px	750px
scaled-large	scale	1024px	1024px
scaled-xlarge	scale	2400px	2400px
square-small	crop	240px	240px
square-small2x	crop	480px	480px
facebook	crop	1200px	630px
twitter	crop	600px	314px

Custom image variants

To request a custom image variant, a sparse attribute definition needs to be accompanied with a corresponding image variant definition. The definition is passed in a imageVariant.[VARIANT NAME] query parameter: ?fields.image=variants.my-variant&imageVariant.my-variant=w:320;h:640;fit:scale.

The imageVariant.* parameter contains semicolon-separated key:value pairs describing the image variant. The following keys and values are supported:

Parameter	Description
w	(integer) Image width. Value must be between 8 and 3072. `w` or `h` can be omitted when fit is `scale`.
h	(integer) Image height. Value must be between 8 and 3072. `w` or `h` can be omitted when fit is `scale`.
fit	(string) Fit mode for resizing the original image. Accepts values `scale` and `crop`. See descriptions of different fit modes below.

The amount of custom variants that can be requested with a single request is limited to 10.

Variant fit modes

Fit mode	Description
scale	Resizes the image to fit within the width and height dimensions preserving the image aspect ratio without cropping. The actual image smaller side will vary depending on the image aspect ratio. If image width or height is omitted image will be scaled using the provided dimension while maintaining aspect ratio.
crop	Resizes the image to fit both dimensions and crops away the excess. Uses edge detection algorithm for determining which portion of the image to center the crop on.

Upload image

HTTP request

POST /v1/integration_api/images/upload

Example request

# Upload portrait.jpg local file
$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/images/upload' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -F "image=@portrait.jpg"

// Upload portrait.jpg local file
// You can pass path to file on the filesystem as a string
integrationSdk.images.upload({
  image: "portrait.jpg"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "5a8f34f6-202c-4916-af7a-53d56004e872",
    "type": "image",
    "attributes": {
      "variants": {
        "default": {
          "width": 720,
          "height": 540,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "5a8f34f6-202c-4916-af7a-53d56004e872"},
    type: "image",
    attributes: {
      variants: {
        default: {
          width: 720,
          height: 540,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        }
      }
    }
  }
}

Command for uploading a new image. The returned image can subsequently be used as a user profile image or a listing image.

The maximum allowed file size is 20MB.

Multipart body parameters

Note that this API endpoint requires that the body be sent as multipart/form-data

Parameter	Description
image	The image content.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
400	image-invalid-content	The uploaded image is in an unsupported format.
413	request-upload-over-limit	The uploaded file is too large.

Transactions

API prefix

/v1/integration_api/transactions

Example resource

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {
        "phoneNumber": "+1-202-555-5555"
      },
      "metadata": {
        "refId": 1234
      },
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {
        phoneNumber: "+1-202-555-5555"
      },
      metadata: {
        refId: 1234
      },
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

The transaction API resource type represents information about transactions.

`transaction` resource format

Attribute	Description
createdAt	(string) The date and time when the transaction was initiated in ISO 8601 format.
processName	(string) The (unique) name for the process this transaction uses
processVersion	(number) The version of the transaction process
lastTransition	(string, timestamp) The name of the last transition that happened in the transaction. See Transaction process.
lastTransitionedAt	(string, timestamp) The date and time when the last transition in the transaction occurred, in ISO 8601 format.
lineItems	(array) Array of line item objects, that represent the pricing breakdown of the transaction.
lineItems.*.code	(string) The line item code. See the table below for list of possible codes.
lineItems.*.unitPrice	(object, money) Unit price.
lineItems.*.quantity	(number, optional) When applicable, the complete number of booked units that the line item represents. When `units` and `seats` are provided `quantity` always equals to `units x seats`. Can be non-integer or negative number.
lineItems.*.units	(number, optional) When applicable, the number of units that the line item represents. Multiplying `units` with `seats` equals `quantity`. Can be non-integer or negative number.
lineItems.*.seats	(number, optional) When applicable, the number of seats that the line item represents. Multiplying `seats` with `units` equals `quantity`. Must be a positive integer.
lineItems.*.percentage	(number, optional) When applicable, the percentage value that the line item represents. Can be negative. E.g. `5.0` (5%).
lineItems.*.lineTotal	(object, money) The line item total value. `amount` can be negative. The line total is always equal to either `quantity x unitPrice` or `percentage x unitPrice / 100`.
lineItems.*.reversal	(boolean) Flag indicating whether the line item is a reversal of another line item. Reversal are added when there has been a reversal (typically a refund).
lineItems.*.includedFor	(array) Array of strings, indicating whether the line item applies to `customer`, `provider` or both. For instance, a commission that the provider pays does not affect the total from the point of view of the customer.
payinTotal	(object, money) The total monetary amount of the payin (i.e. the amount paid by the customer). This amount is the sum total of all line items that apply to the customer (i.e. have `customer` in their `includedFor` lists).
payoutTotal	(object, money) The total monetary amount of the payout (i.e. the amoun paid to the provider). This amount is the sum total of all line items that apply to the provider (i.e. have `provider` in their `includedFor` lists).
protectedData	(object) Transaction's protected data. See Extended data for details.
metadata	(object) Transaction's metadata. See Extended data for details.
transitions	(array) The transaction's transition history - list of transition objects, in chronological order.
transitions.*.transition	(string) The name of the transition. See Transaction process.
transitions.*.createdAt	(string, timestamp) The date and time when the transition occurred in ISO 8601 format.
transitions.*.by	(string) The actor that performed the transition. One of `customer`, `provider`, `operator` or `system`.

The following table lists all currently available codes. Depending on your transaction process, the codes that your marketplace uses is a subset of the ones listed below.

Line item code	Description
line-item/day	Line item representing the price of daily booking for given number of days.
line-item/night	Line item representing the price of nightly booking for given number of nights.
line-item/units	Line item representing the price of units for given quantity.
line-item/units1	Line item representing the price of units type "1" for given quantity in a two unit transaction.
line-item/units2	Line item representing the price of units type "2" for given quantity in a two unit transaction.
line-item/negotiation	Line item representing negotiated change to the total price.
line-item/provider-commission	Line item representing commission that is paid by the provider.
line-item/customer-commission	Line item representing commission that is paid by the customer.
line-item/provider-fixed-commission	Line item representing a fixed commission that is paid by the provider.
line-item/customer-fixed-commission	Line item representing a fixed commission that is paid by the customer.
line-item/<custom code>	With custom pricing the line item code can be any string with `line-item/` prefix and a maximum length of 64 characters.

`transaction` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the transaction.
listing	listing	one	The listing that the transaction is about. Supported nested relationships: `listing.images`, `listing.currentStock`.
provider	user	one	The user who is author of the listing that the transaction is about. Supported nested relationships: `provider.profileImage`.
customer	user	one	The customer who initiated the transaction. Supported nested relationships: `customer.profileImage`.
booking	booking	one	(optional) The booking created by the transaction, if any.
stockReservation	stockReservation	one	(optional) The stock reservation created by the transaction, if any. Supported nested relationships: `stockReservation.stockAdjustments`.
reviews	review	many	(optional) The reviews of the parties in the transaction, if any. Supported nested relationships: `reviews.author`, `reviews.author.profileImage`, `reviews.subject`, `reviews.subject.profileImage`.
messages	message	many	(optional) The messages that the parties have sent to one another as part of the transaction, if any. Note that there may be large number of messages. It is therefore recommended to use limits when including this relationship. Supported nested relationships: `messages.sender`, `messages.sender.profileImage`.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show transaction

HTTP request

GET /v1/integration_api/transactions/show

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/transactions/show?id=ef98e897-5b81-49a5-aca6-01d9759df075' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.transactions.show({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          unit: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

Query returning data about given transaction.

Query parameters

Parameter	Description
id	The ID of the transaction.

Query transactions

HTTP request

GET /v1/integration_api/transactions/query

Example request

# Query transactions where the user is provider and the last transition is 'transition/request'
$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/transactions/query' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Query transactions where the user is provider and the last transition is 'transition/request'
integrationSdk.transactions.query().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
      "type": "transaction",
      "attributes": {
        "createdAt": "2018-03-27T12:30:02.000Z",
        "processName": "preauth-with-nightly-booking",
        "processVersion": 3,
        "lastTransition": "transition/request",
        "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
        "payinTotal": {
          "amount": 6360,
          "currency": "USD"
        },
        "payoutTotal": {
          "amount": 5724,
          "currency": "USD"
        },
        "lineItems": [
          {
            "code": "line-item/day",
            "quantity": 4,
            "units": 2,
            "seats": 2,
            "reversal": false,
            "unitPrice": {
              "amount": 1590,
              "currency": "USD"
            },
            "lineTotal": {
              "amount": 6360,
              "currency": "USD"
            },
            "includeFor": [
              "customer",
              "provider"
            ]
          },
          {
            "code": "line-item/provider-commission",
            "percentage": -10.0,
            "reversal": false,
            "unitPrice": {
              "amount": 6360,
              "currency": "USD"
            },
            "lineTotal": {
              "amount": -636,
              "currency": "USD"
            },
            "includeFor": [
              "provider"
            ]
          }
        ],
        "protectedData": {},
        "transitions": [
          {
            "transition": "transition/request",
            "createdAt": "2018-03-27T12:30:03.100Z",
            "by": "customer"
          }
        ]
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
      type: "transaction",
      attributes: {
        createdAt: new Date("2018-03-27T12:30:02.000Z"),
        processName: "preauth-with-nightly-booking",
        processVersion: 3,
        lastTransition: "transition/request",
        lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
        payinTotal: {
          amount: 6360,
          currency: "USD"
        },
        payoutTotal: {
          amount: 5724,
          currency: "USD"
        },
        lineItems: [
          {
            code: "line-item/day",
            quantity: 4,
            units: 2,
            seats: 2,
            reversal: false,
            unitPrice: {
              amount: 1590,
              currency: "USD"
            },
            lineTotal: {
              amount: 6360,
              currency: "USD"
            },
            includeFor: [
              "customer",
              "provider"
            ]
          },
          {
            code: "line-item/provider-commission",
            percentage: -10.0,
            reversal: false,
            unitPrice: {
              amount: 6360,
              currency: "USD"
            },
            lineTotal: {
              amount: -636,
              currency: "USD"
            },
            includeFor: [
              "provider"
            ]
          }
        ],
        protectedData: {},
        transitions: [
          {
            transition: "transition/request",
            createdAt: new Date("2018-03-27T12:30:03.100Z"),
            by: "customer"
          }
        ]
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 3,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query all transactions of a marketplace. Results are sorted by transaction's createdAt time in descending order (i.e. most recent transactions are returned first).

Query parameters

Parameter	Description
createdAtStart	(timestamp, optional) Filter transactions by `createdAt` time. Only transactions created on or after the given time are returned. The timestamp must be in ISO 8601 format.
createdAtEnd	(timestamp, optional) Filter transactions by `createdAt` time. Only transactions created before the given time are returned. The timestamp must be in ISO 8601 format.
userId	(uuid, optional) Return only transactions where the user with the given ID is either a customer or provider.
customerId	(uuid, optional) Return only transactions in which the user with the given ID is a customer.
providerId	(uuid, optional) Return only transactions in which the user with the given ID is a provider.
listingId	(uuid, optional) Return only transactions for the given listing.

Transition transaction

HTTP request

POST /v1/integration_api/transactions/transition

Example request

# Example transition assiming a process where the operator accepts transactions
$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/transactions/transition' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075"
  "transition": "transition/accept",
  "params": {}
}'

// Example transition assiming a process where the operator accepts transactions
integrationSdk.transactions.transition({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075"),
  transition: "transition/accept",
  params: {}
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/accept",
      "lastTransitionedAt": "2018-03-27T13:35:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        },
        {
          "transition": "transition/accept",
          "createdAt": "2018-03-27T13:35:03.100Z",
          "by": "operator"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/accept",
      lastTransitionedAt: new Date("2018-03-27T13:35:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        },
        {
          transition: "transition/accept",
          createdAt: new Date("2018-03-27T13:35:03.100Z"),
          by: "operator"
        }
      ]
    }
  }
}

Command that transitions an existing transaction to a new state via a given transition.

Only transitions where the actor is :actor.role/operator can be made through this API.

Body parameters

Parameter	Description
id	(uuid) The ID of the transaction.
transition	(string) The name of one of your transaction process' possible next transitions for the current transaction state.
params	(object) The parameters for the transition, according to your transaction process definition.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
402	transaction-payment-failed	Payment information was invalid or the payment was rejected by Stripe. Additional information can be found in the error `meta.stripeMessage`, `meta.stripeCode` and `meta.stripeDeclineCode`. See also Stripe errors documentation.
403	forbidden	The API client is not authorized to perform the given transition.
409	transaction-invalid-transition	The given transition is not defined in the process or it is not one of the possible next transitions for the current transaction state.
409	transaction-invalid-action-sequence	The given transition cannot be executed because the action sequence is invalid and some action precondition is not met. The problem relates to the process description as a whole rather than just the transition in question.
409	transaction-locked	The transaction is currently locked by another operation. Try again, but consider that it's likely that the transaction has already transitioned to a different state.
409	transaction-provider-banned-or-deleted	The provider in the transaction is banned or deleted and the transaction cannot be transitioned.
409	transaction-customer-banned-or-deleted	The customer in the transaction is banned or deleted and the transaction cannot be transitioned.

Speculatively transition transaction

HTTP request

POST /v1/integration_api/transactions/transition_speculative

Example request

# Example transition assiming a process where the operator accepts transactions
$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/transactions/transition_speculative' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075"
  "transition": "transition/accept",
  "params": {}
}'

// Example transition assiming a process where the operator accepts transactions
integrationSdk.transactions.transitionSpeculative({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075"),
  transition: "transition/accept",
  params: {}
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/accept",
      "lastTransitionedAt": "2018-03-27T13:35:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        },
        {
          "transition": "transition/accept",
          "createdAt": "2018-03-27T13:35:03.100Z",
          "by": "operator"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/accept",
      lastTransitionedAt: new Date("2018-03-27T13:35:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        },
        {
          transition: "transition/accept",
          createdAt: new Date("2018-03-27T13:35:03.100Z"),
          by: "operator"
        }
      ]
    }
  }
}

Command that simulates transitioning an existing transaction to a new state. The transition is not actually performed and the transaction state is not changed. This command can be used to validate the parameters or to get updated transaction price breakdown (via lineItems), as if a real transition were performed.

Only transitions where the actor is :actor.role/operator can be made through this API.

Body parameters

Parameter	Description
id	(uuid) The ID of the transaction.
transition	(string) The name of one of your transaction process' possible next transitions for the current transaction state.
params	(object) The parameters for the transition, according to your transaction process definition.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	The API client is not authorized to perform the given transition.
409	transaction-invalid-transition	The given transition is not defined in the process or it is not one of the possible next transitions for the current transaction state.
409	transaction-invalid-action-sequence	The given transition cannot be executed because the action sequence is invalid and some action precondition is not met. The problem relates to the process description as a whole rather than just the transition in question.
409	transaction-locked	The transaction is currently locked by another operation. Try again, but consider that it's likely that the transaction has already transitioned to a different state.
409	transaction-provider-banned-or-deleted	The provider in the transaction is banned or deleted and the transaction cannot be transitioned.
409	transaction-customer-banned-or-deleted	The customer in the transaction is banned or deleted and the transaction cannot be transitioned.

Update transaction metadata

HTTP request

POST /v1/integration_api/transactions/update_metadata

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/transactions/update_metadata \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075"
  "metadata": {
    "extId": 1234,
    "promotionDiscount": 20
  }
}'

integrationSdk.transactions.updateMetadata({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075"),
  metadata: {
    extId: 1234,
    promotionDiscount: 20
  }
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/accept",
      "lastTransitionedAt": "2018-03-27T13:35:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "metadata": {
        "source": "CAMPAIGN-A",
        "extId": 1234,
        "promotionDiscount": 20
      },
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        },
        {
          "transition": "transition/accept",
          "createdAt": "2018-03-27T13:35:03.100Z",
          "by": "operator"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/accept",
      lastTransitionedAt: new Date("2018-03-27T13:35:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      metadata: {
        source: "CAMPAIGN-A",
        extId: 1234,
        promotionDiscount: 20
      },
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        },
        {
          transition: "transition/accept",
          createdAt: new Date("2018-03-27T13:35:03.100Z"),
          by: "operator"
        }
      ]
    }
  }
}

Command that updates the transaction's metadata.

Body parameters

Parameter	Description
id	(uuid) The ID of the transaction.
metadata	(object, optional) Transaction's public metadata. See Extended data. The total size of the metadata object as JSON string must not exceed 50KB. The given `metadata` object is merged with the existing `metadata` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the transaction's `metadata`.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
409	transaction-locked	The transaction is currently locked by another operation. Try again, but consider that it's likely that the transaction has already transitioned to a different state.

Bookings

Example resource

{
  "data": {
    "id": "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1",
    "type": "booking",
    "attributes": {
      "seats": 3,
      "start": "2018-04-20T00:00:00.000Z",
      "end": "2018-04-22T00:00:00.000Z",
      "displayStart": "2018-04-20T18:00:00.000Z",
      "displayEnd": "2018-04-22T10:00:00.000Z",
      "state": "accepted"
    }
  }
}

{
  data: {
    id: UUID {uuid: "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1"},
    type: "booking",
    attributes: {
      seats: 3,
      start: new Date("2018-04-20T00:00:00.000Z"),
      end: new Date("2018-04-22T00:00:00.000Z"),
      displayStart: new Date("2018-04-20T18:00:00.000Z"),
      displayEnd: new Date("2018-04-22T10:00:00.000Z"),
      state: "accepted"
    }
  }
}

The booking resource type represents information about a booking.

Bookins are currently accessible only via the booking relationship of transaction resources.

`booking` resource format

Attribute	Description
seats	(number) Integer number of booked seats.
start	(string, timestamp) The date and time the booking starts. This time is used to determine what interval is matched against the listing's availability and is reserved with the booking.
end	(string, timestamp) The date and time the booking ends. The range is exclusive on the `end` side, i.e. the `end` is not reserved. This time is used to determine what interval is matched against the listing's availability and is reserved with the booking.
displayStart	(string, timestamp) The booking start display time. The display time is an arbitrary timestamp and can be different from the `start` time.
displayEnd	(string, timestamp) The booking end display time. The display time is an arbitrary timestamp and can be different from the `end` time.
state	(string) The state of the booking. See booking states.

Note that if your transaction process uses daily or nightly bookings, only the date component of the timestamp is relevant. In that case the time component of start and end timestamps is normalized to 00:00:00.000Z time but you have to interpret the timestamp in UTC time zone in order to get the correct date.

The booking displayStart and displayEnd times can optionally be set when a booking is created via a transaction. If omitted, the displayStart and displayEnd will have the same values as start and end respectively. If set, displayStart and displayEnd are stored and returned unmodified by the API (i.e. no normalization is performed for them for day- and night-based bookings, unlike the start and end times).

`booking` states

State	Reserves time slot	Description
pending	yes	A new booking that has been requested.
proposed	no	A new booking that has been proposed.
accepted	yes	A booking that has been accepted.
declined	no	A booking that has been declined before it was accepted.
cancelled	no	A booking that has been cancelled after it was accepted.

For more information about bookings, booking states and availability management, see Listing availability management.

`booking` relationships

Relationship	Resource type	Cardinality	Description
transaction	transaction	one	The transaction corresponding to a given booking.
listing	listing	one	The listing corresponding to a given booking.

Stock

API prefix

/v1/integration_api/stock/

Example resource

{
  "data": {
    "id": "22e9df61-a655-4491-bdfc-494e95072f58",
    "type": "stock",
    "attributes": {
      "quantity": 10
    }
  }
}

{
  data: {
    id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"},
    type: "stock",
    attributes: {
      quantity: 10
    }
  }
}

The stock API resource type represents information about the available stock of a listing. stock resources are currently only available via the currentStock relationship of listing resources.

`stock` resource format

Attribute	Description
quantity	(integer) The quantity of available stock. Under normal operation this number is non-negative. See Negative stock quantity for more details.

Compare and set total stock

HTTP request

POST /v1/integration_api/stock/compare_and_set

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/stock/compare_and_set?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "oldTotal": 8,
  "newTotal": 10
}'

integrationSdk.stock.compareAndSet({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  oldTotal: 8,
  newTotal: 10
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "22e9df61-a655-4491-bdfc-494e95072f58",
    "type": "stock",
    "attributes": {
      "quantity": 10
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"},
    type: "stock",
    attributes: {
      quantity: 10
    }
  }
}

Command that sets the total available stock for a listing. Internally, the command creates a new stock adjustment, such that the listing's total available stock becomes the given newTotal quantity.

This command guarantees that the stock adjustment will be created if and only if the listing's available stock quantity prior to the command matches the given oldTotal quantity.

If oldTotal and newTotal are equal, a new stock adjustment is not created and the command is a no-op.

Body parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
oldTotal	(integer) The quantity of listing stock that the listing must have prior to the command execution in order for the new total to be set. Must be set to `null` if the listing does not have stock defined at all.
newTotal	(integer) The total quantity of stock that the listing will have after the command is successfully executed. Must be a non-negative number.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Stock adjustments

API prefix

/v1/integration_api/stock_adjustments/

Example resource

{
  "data": {
    "id": "daec15c8-506f-40c3-828f-a1f064c06592",
    "type": "stockAdjustment",
    "attributes": {
      "at": "2021-09-07T10:00:00.000Z",
      "quantity": 2
    }
  }
}

{
  data: {
    id: UUID {uuid: "daec15c8-506f-40c3-828f-a1f064c06592"},
    type: "stockAdjustment",
    attributes: {
      at: new Date("2021-09-07T10:00:00.000Z"),
      quantity: 2
    }
  }
}

The stockAdjustment API resource type represents information about a change in the quantity of available stock of a listing. The total available stock is the sum of all adjustments.

Stock adjustments are immutable and will never change.

`stockAdjustment` resource format

Attribute	Description
at	(string, timestamp) The date and time when the stock adjustment takes effect in ISO 8601 format.
quantity	(integer) The quantity of the adjustment. A positive number indicates increase in available stock, while a negative number indicates a reduction. A quantity of 0 is only possible for an initial stock adjustment that sets the listing's available stock to 0.

`stockAdjustment` relationships

Relationship	Resource type	Cardinality	Description
listing	listing	one	The listing to which the stock adjustment applies. Supported nested relationships: `listing.currentStock`, `listing.author`.
stockReservation	stockReservation	one	(optional) The stock reservation, as a result of which the stock adjustment was created, if any. Supported nested relationships: `stockReservation.transaction`, `stockReservation.transaction.customer`, `stockReservation.transaction.provider`.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Query stock adjustments

HTTP request

GET /v1/integration_api/stock_adjustments/query

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/stock_adjustments/query?listingId=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&start=2021-09-07T00:00:00.000Z&end=2021-09-10T00:00:00.000Z' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.stockAdjustments.query({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2021-09-07T00:00:00.000Z"),
  end: new Date("2021-09-10T00:00:00.000Z")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "daec15c8-506f-40c3-828f-a1f064c06592",
      "type": "stockAdjustment",
      "attributes": {
        "at": "2021-09-07T10:00:00.000Z",
        "quantity": 2
      }
    }
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "daec15c8-506f-40c3-828f-a1f064c06592"},
      type: "stockAdjustment",
      attributes: {
        at: new Date("2021-09-07T10:00:00.000Z"),
        quantity: 2
      }
    }
    {...},
    {...}
  ],
  meta: {
    totalItems: 5,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query that returns all the stock adjustments of a given listing for a given time range (i.e. have at timestamp within the given range). The results are ordered by the stock adjustment's at timestamp in increasing order (i.e. oldest stock adjustments are returned first).

Include the ownListing.currentStock nested relationship in order to obtain the current total listing stock at the time of query. Since past stock adjustments are immutable, this allows to compute the available stock at any past point in time by summing up the applicable adjustments starting from the current total available stock.

Query parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
start	(timestamp) Filter stock adjustments by `at` time. Only stock adjustments with `at` time greater than or equal to the given timestamp are returned. The timestamp is in ISO 8601 format. The start time must be between 366 days in the past and 1 day in the future.
end	(timestamp) Filter stock adjustments by `at` time. Only stock adjustments with `at` time less than the given timestamp are returned. The timestamp is in ISO 8601 format. The end time must be after the `start` time and at most 1 day in the future and at most 366 days from the `start` time.

Create stock adjustment

HTTP request

POST /v1/integration_api/stock_adjustments/create

Example request

$ curl -X POST 'https://flex-integ-api.sharetribe.com/v1/integration_api/stock_adjustments/create?expand=true,include=ownListing.currentStock' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "quantity": 2
}'

integrationSdk.stockAdjustments.create({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  quantity: 2
}, {
  expand: true,
  include: ["ownListing.currentStock"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "daec15c8-506f-40c3-828f-a1f064c06592",
    "type": "stockAdjustment",
    "attributes": {
      "at": "2021-09-07T10:00:00.000Z",
      "quantity": 2
    },
    "relationships": {
      "ownListing": {
          "data": {"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f", "type": "ownListing"}
      }
    }
  },
  "included": [
    {
      "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
      "type": "ownListing",
      "attributes": {...}
      "relationships": {
        "currentStock": {
          "data": {"id": "22e9df61-a655-4491-bdfc-494e95072f58", "type": "stock"}
        }
      }
    },
    {
      "id": "22e9df61-a655-4491-bdfc-494e95072f58",
      "type": "stock",
      "attributes": {
        "quantity": 10
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "daec15c8-506f-40c3-828f-a1f064c06592"},
    type: "stockAdjustment",
    attributes: {
      at: new Date("2021-09-07T10:00:00.000Z"),
      quantity: 2
    },
    relationships: {
      ownListing: {
        data: {id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}, type: "ownListing"}
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
      type: "ownListing",
      attributes: {...},
      relationships: {
        currentStock: {
          data: {id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"}, type: "stock"}
        }
      }
    },
    {
      id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"},
      type: "stock",
      attributes: {
        quantity: 10
      }
    }
  ]
}

Command that creates a new stock adjustment for a given listing. The new adjustment takes effect immediately.

Include the ownListing.currentStock nested relationship in order to obtain the current total listing stock with the new adjustment taken into account.

Body parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
quantity	(integer) The quantity of the adjustment. A positive number indicates increase in available stock, while a negative number indicates a reduction. It is not possible to create stock adjustments with 0 quantity.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Stock reservations

API prefix

/v1/integration_api/stock_reservations/

Example resource

{
  "data": {
    "id": "2b78155f-fba6-491e-b842-d83d23ea657e",
    "type": "stockReservation",
    "attributes": {
      "quantity": 2,
      "state": "pending"
    }
  }
}

{
  data: {
    id: UUID {uuid: "2b78155f-fba6-491e-b842-d83d23ea657e"},
    type: "stockReservation",
    attributes: {
      quantity: 2,
      state: "pending"
    }
  }
}

The stockReservation API resource type represents information about a stock reservation.

`stockReservation` resource format

Attribute	Description
quantity	(integer) The quantity of reserved stock.
state	(string) The state of the stock reservation. See stock reservation states.

Stock reservation states

State	Reserves stock	Description
pending	yes	A new stock reservation that has been requested.
proposed	no	A new stock reservation that has been proposed.
accepted	yes	A stock reservation that has been accepted.
declined	no	A stock reservation that has been declined before it was accepted.
cancelled	no	A stock reservation that has been cancelled after it was accepted.

For more information, see also stock reservation states section in the documentation the transaction process actions related to stock reservations.

`stockReservation` relationships

Relationship	Resource type	Cardinality	Description
listing	listing	one	The listing to which the stock reservation applies. Supported nested relationships: `listing.author`, `listing.currentStock`.
transaction	transaction	one	The transaction corresponding to the stock reservation. Supported nested relationships: `transaction.customer`, `transaction.provider`.
stockAdjustments	stockAdjustment	many	The set of stock adjustments that were created as a result of the stock reservation.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show stock reservation

HTTP request

GET /v1/integration_api/stock_reservations/show

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/stock_reservations/show?id=2b78155f-fba6-491e-b842-d83d23ea657e' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.stockReservations.show({
  id: new UUID("2b78155f-fba6-491e-b842-d83d23ea657e"),
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "2b78155f-fba6-491e-b842-d83d23ea657e",
    "type": "stockReservation",
    "attributes": {
      "quantity": 2,
      "state": "pending"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "2b78155f-fba6-491e-b842-d83d23ea657e"},
    type: "stockReservation",
    attributes: {
      quantity: 2,
      state: "pending"
    }
  }
}

Query returning data about given stock reservation.

Query parameters

Parameter	Description
id	(uuid) The ID of the stock reservation.

Reviews

API prefix

/v1/integration_api/reviews

Example resource

{
  "data": {
    "id": "81a0170a-ecc2-4fe1-9aae-e86226023717",
    "type": "review",
    "attributes": {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": "2018-04-25T11:10:14.123Z",
      "deleted": false
    }
  }
}

{
  data: {
    id: UUID {uuid: "81a0170a-ecc2-4fe1-9aae-e86226023717"},
    type: "review",
    attributes: {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": new Date("2018-04-25T11:10:14.123Z"),
      "deleted": false
    }
  }
}

The review resource format represent reviews posted by transaction parties about one another. Reviews are only posted during a transaction through the transaction process.

Reviews are currently accessible only via the reviews relationship of transaction resources.

`review` resource format

Attribute	Description
type	(string) The review type - one of `ofProvider` or `ofCustomer`. `ofProvider` reviews are written by customers in a transaction and are considered as reviews about both the provider and the listing in that transaction. `ofCustomer` reviews are written by providers and are about the customer in the transaction.
state	(string) The review state - one of `public` or `pending`.
rating	(number, integer) The rating given with the review. An integer from 1 to 5, inclusive.
content	(string) The content of the view.
createdAt	(string, timestamp) The date and time the review was written, in ISO 8601 format.
deleted	(boolean) Flag indicating whether the review has been deleted. If true, all other attributes of the review will be returned as default values (false for booleans and null for all else). Used when relationship requires a deleted review.

`review` relationships

Relationship	Resource type	Cardinality	Description
author	user	one	The user that wrote the review.
listing	listing	one	The listing that the review is about. The relationship is available only for reviews of type `ofProvider`.
subject	user	one	The user that the review is about.
transaction	transaction	one	The transaction corresponding to a given review.

Messages

API prefix

/v1/integration_api/messages

Example resource

{
  "data": {
    "id": "efe37293-5e58-4f8d-8507-64616e34d22e",
    "type": "message",
    "attributes": {
      "content": "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      "createdAt": "2018-03-28T09:12:58.866Z"
    }
  }
}

{
  data: {
    id: UUID {uuid: "efe37293-5e58-4f8d-8507-64616e34d22e"},
    type: "message",
    attributes: {
      content: "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      createdAt: new Date("2018-03-28T09:12:58.866Z")
    }
  }
}

The message resource type represents transaction messages that are sent between users as part of a conversation about transaction. Messages are always linked to a transaction.

Messages are currently accessible only via the messages relationship of transaction resources.

`message` resource format

Attribute	Description
content	(string) The message content.
createdAt	(string, timestamp) The date and time the message was sent in ISO 8601 format.

`message` relationships

Relationship	Resource type	Cardinality	Description
sender	user	one	The user that sent the message. Supported nested relationships: `sender.profileImage`.
transaction	transaction	one	The transaction that the message refers to.

Events

API prefix

/v1/integration_api/events

Example resource

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "event",
    "attributes": {
      "eventType": "listing/updated",
      "sequenceId": 12345678,
      "createdAt": "2020-11-27T12:30:02.000Z",
      "marketplaceId": "9deec37c-b59c-4884-8f60-e4944335c327",
      "source": "source/marketplace-api",
      "resourceId": "5bbb2f6f-568f-470a-9949-a655e3f6ac46",
      "resourceType": "listing",
      "resource": {
        "id": "5bbb2f6f-568f-470a-9949-a655e3f6ac46",
        "type": "listing",
        "attributes": {
          "title": "Peugeot eT101",
          "description": "7-speed Hybrid",
          "deleted": false,
          "geolocation": {
            "lat": 40.64542,
            "lng": -74.08508
          },
          "createdAt": "2018-03-23T08:40:24.443Z",
          "state": "published",
          "availabilityPlan": null,
          "privateData": {
            "externalServiceId": "abcd-service-id-1234"
          },
          "publicData": {
            "address": {
              "city": "New York",
              "country": "USA",
              "state": "NY",
              "street": "230 Hamilton Ave"
            },
            "category": "road",
            "gears": 22
            "rules": "This is a nice, bike! Please, be careful with it."
          },
          "metadata": {
            "promoted": true
          },
          "price": {
            "amount": 1590,
            "currency": "USD"
          }
        },
        "relationships": {
          "author": {"data": {"id": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a", "type": "user"}},
          "marketplace": {"data": {"id": "9deec37c-b59c-4884-8f60-e4944335c327", "type": "marketplace"}},
          "images": {
            "data": [
              {"id": "209a25aa-e7cf-4967-89c3-0f09b2d482ff", "type": "image"},
              {"id": "98e11f3b-ea22-4b1b-8549-e543ae241133", "type": "image"},
              {"id": "ee1a647a-a751-43c7-90a4-48e94654f016", "type": "image"}
            ]
          }
        }
      },
      "previousValues": {
        "attributes": {
          "title": "old title",
          "publicData": {
            "address": {
              "city": "New York",
              "country": "USA",
              "state": "NY",
              "street": "222 Hamilton Ave"
            },
            "rules": null
          }
        },
        "relationships": {
          "images": {
            "data": [
              {"id": "98e11f3b-ea22-4b1b-8549-e543ae241133", "type": "image"},
              {"id": "d12b8ebc-4df8-4bd0-9231-2f05691831a4", "type": "image"}
            ]
          }
        }

      },
      "auditData": {
        "userId": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a",
        "adminId": null,
        "clientId": "69ea8198-201c-48c4-a3bb-78b38e4059b0",
        "requestId": "4b66e510-22cb-47ca-953f-8a8377af2ed0"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "event",
    attributes: {
      eventType: "listing/updated",
      sequenceId: 12345678,
      createdAt: new Date("2020-11-27T12:30:02.000Z"),
      marketplaceId: UUID {uuid: "9deec37c-b59c-4884-8f60-e4944335c327"},
      source: "source/marketplace-api",
      resourceId: UUID {uuid: "5bbb2f6f-568f-470a-9949-a655e3f6ac46"},
      resourceType: "listing",
      resource: {
        id: UUID {uuid: "5bbb2f6f-568f-470a-9949-a655e3f6ac46"},
        type: "listing",
        attributes: {
          title: "Peugeot eT101",
          description: "7-speed Hybrid",
          deleted: false,
          geolocation: LatLng {lat: 40.64542, lng: -74.08508},
          createdAt: new Date("2018-03-23T08:40:24.443Z"),
          state: "published",
          availabilityPlan: null,
          privateData: {
            externalServiceId: "abcd-service-id-1234"
          },
          publicData: {
            address: {
              city: "New York",
              country: "USA",
              state: "NY",
              street: "230 Hamilton Ave"
            },
            category: "road",
            gears: 22,
            rules: "This is a nice, bike! Please, be careful with it."
          },
          metadata: {
            promoted: true
          },
          price: Money {amount: 1590, currency: "USD"}
        },
        relationships: {
          author: {data: {id: UUID {uuid: "5cf4c0eb-513f-419b-a8be-bdb6c14be10a"}, type: "user"}},
          marketplace: {data: {id: UUID {uuid: "9deec37c-b59c-4884-8f60-e4944335c327"}, type: "marketplace"}},
          images: {
            data: [
              {id: UUID {uuid: "209a25aa-e7cf-4967-89c3-0f09b2d482ff"}, type: "image"},
              {id: UUID {uuid: "98e11f3b-ea22-4b1b-8549-e543ae241133"}, type: "image"},
              {id: UUID {uuid: "ee1a647a-a751-43c7-90a4-48e94654f016"}, type: "image"}
            ]
          }
        }
      },
      previousValues: {
        attributes: {
          title: "old title",
          publicData: {
            address: {
              city: "New York",
              country: "USA",
              state: "NY",
              street: "222 Hamilton Ave"
            },
            rules: null
          }
        },
        relationships: {
          images: {
            data: [
              {id: UUID {uuid: "98e11f3b-ea22-4b1b-8549-e543ae241133"}, type: "image"},
              {id: UUID {uuid: "d12b8ebc-4df8-4bd0-9231-2f05691831a4"}, type: "image"}
            ]
          }
        }
      },
      auditData: {
        userId: UUID {uuid: "5cf4c0eb-513f-419b-a8be-bdb6c14be10a"},
        adminId: null,
        clientId: UUID {uuid: "69ea8198-201c-48c4-a3bb-78b38e4059b0"},
        requestId: UUID {uuid: "4b66e510-22cb-47ca-953f-8a8377af2ed0"}
      }
    }
  }
}

The event API resource type represents information about an event.

`event` resource format

Attribute	Description
createdAt	(timestamp) The date and time when the event occurred in ISO 8601 format.
sequenceId	(integer) A numeric ID for the event that provides a strict total ordering of events, i.e. later events are guaranteed to have a sequence ID that is strictly larger than earlier events.
marketplaceId	(uuid) The ID of the marketplace in which the event happened.
eventType	(string) The type of the event. See supported event types. The event type has the form `RESOURCE_TYPE/EVENT_SUBTYPE`. E.g. `listing/created`.
source	(string) The service from which the event originated. See event sources.
resourceId	(uuid) The ID of the API resource that the event is about, e.g. a user or a listing ID.
resourceType	(string) The type of the API resource that the event is about. This is one of the API resource types supported in the Integration API (e.g. `user`, `listing`, etc).
resource	(object) The value of the resource, for which the event is about, after the event occurred. For all event types except `/deleted` events, the `resource` attribute is populated. For `/deleted` events, `resource` is `null`. The resource data is the same as if the resource is retrieved through the Integration API. For details see the reference for event data and previous values.
previousValues	(object) An object describing the previous values for the event's charnged resource attributes and relationships, if any. Note that for `*/deleted` events, some of the attributes may be `null`, due to stricter data deletion requirements. For details see the reference for event data and previous values.
auditData	(object) Data about the actor that caused the event.
auditData.userId	(uuid) The ID of the Sharetribe marketplace user that caused the event, if any. This attribute is set for most events that occurr in the Marketplace API and is `null` otherwise.
auditData.adminId	(uuid) The ID of the Sharetribe Console admin user that caused the event. Typically set for events that occur in Console, but can be set in combination with `userId` when an admin has used the "login as" Console feature and acted on behalf of a marketplace user though the Marketplace API.
auditData.requestId	(uuid) The ID of the API request that caused the event. Can be `null`. Currently this information is meaningless but might have future uses.
auditData.clientId	(uuid) The client ID of the Sharetribe Application that caused the event. This attribute is set if the event was caused by an API call from a Sharetribe Marketplace API or Integration API application and is `null` otherwise.

`event` relationships

The event resource does not currently have any relationships to other resources.

Query events

HTTP request

GET /v1/integration_api/events/query

Example request

$ curl 'https://flex-integ-api.sharetribe.com/v1/integration_api/events/query?startAfterSequenceId=1234' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.events.query({startAfterSequenceId: 1234}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "8c48efe1-2b36-4799-acca-e419898b3cdd",
      "type": "event",
      "attributes": {
        "eventType": "message/created",
        "sequenceId": 1235,
        "createdAt": "2020-10-20T12:30:02.000Z",
        "marketplaceId": "9deec37c-b59c-4884-8f60-e4944335c327",
        "source": "source/marketplace-api",
        "resourceId": "cd29c0db-a74d-4357-b778-9854611bb42a",
        "resourceType": "message",
        "resource": {
          "id": "cd29c0db-a74d-4357-b778-9854611bb42a",
          "type": "message",
          "attributes": {
            "content": "Hello!",
            "createdAt": "2020-10-20T12:30:01.950Z"
          },
          "relationships": {
            "sender": {"data": {"id": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a", "type": "user"}},
            "transaction": {"data": {"id": "33f2675c-7ff2-402e-9cce-1c78e04851d1", "type": "transaction"}}
          }
        },
        "previousValues": {},
        "auditData": {
          "userId": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a",
          "adminId": null,
          "clientId": "69ea8198-201c-48c4-a3bb-78b38e4059b0",
          "requestId": "e2e7366c-b37d-4e07-ad17-f7c4ab111c33"
        }
      }
    },
    {
      "id": "7515883e-0cee-422f-bf84-31c7e329b9a8",
      "type": "event",
      "attributes": {
        "eventType": "availabilityException/deleted",
        "sequenceId": 1237,
        "createdAt": "2020-10-20T12:30:11.000Z",
        "marketplaceId": "9deec37c-b59c-4884-8f60-e4944335c327",
        "source": "source/marketplace-api",
        "resourceId": "174f00f5-dc7c-4078-8937-26de60ff5418",
        "resourceType": "availabilityException",
        "resource": null,
        "previousValues": {
          "attributes": {
            "seats": 0,
            "start": "2020-12-03T00:00:00.000Z",
            "end": "2020-12-04T00:00:00.000Z"
          },
          "relationships": {
            "listing": {"data": {"id": "6b19f8a8-d87a-47ae-9f59-658befb07613", "type": "listing"}}
          }
        },
        "auditData": {
          "userId": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a",
          "adminId": null,
          "clientId": "69ea8198-201c-48c4-a3bb-78b38e4059b0",
          "requestId": "636427e1-edde-46f3-a541-928e14279f61"
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": null,
    "totalPages": null,
    "page": 1,
    "perPage": 100,
    "paginationUnsupported": true
  }
}

{
  "data": [
    {
      id: UUID {uuid: "8c48efe1-2b36-4799-acca-e419898b3cdd"},
      type: "event",
      attributes: {
        eventType: "message/created",
        sequenceId: 1235,
        createdAt: new Date("2020-10-20T12:30:02.000Z"),
        marketplaceId: UUID {uuid: "9deec37c-b59c-4884-8f60-e4944335c327"},
        source: "source/marketplace-api",
        resourceId: UUID {uuid: "cd29c0db-a74d-4357-b778-9854611bb42a"},
        resourceType: "message",
        resource: {
          id: UUID {uuid: "cd29c0db-a74d-4357-b778-9854611bb42a"},
          type: "message",
          attributes: {
            content: "Hello!",
            createdAt: new Date("2020-10-20T12:30:01.950Z")
          },
          relationships: {
            sender: {data: {id: UUID {uuid: "5cf4c0eb-513f-419b-a8be-bdb6c14be10a"}, type: "user"}},
            transaction: {data: {id: UUID {uuid: "33f2675c-7ff2-402e-9cce-1c78e04851d1"}, type: "transaction"}}
          }
        },
        previousValues: {},
        auditData: {
          userId: UUID {uuid: "5cf4c0eb-513f-419b-a8be-bdb6c14be10a"},
          adminId: null,
          clientId: UUID {uuid: "69ea8198-201c-48c4-a3bb-78b38e4059b0"},
          requestId: UUID {uuid: "e2e7366c-b37d-4e07-ad17-f7c4ab111c33"}
        }
      }
    },
    {
      id: UUID {uuid: "7515883e-0cee-422f-bf84-31c7e329b9a8"},
      type: "event",
      attributes: {
        eventType: "availabilityException/deleted",
        sequenceId: 1237,
        createdAt: new Date("2020-10-20T12:30:11.000Z"),
        marketplaceId: UUID {uuid: "9deec37c-b59c-4884-8f60-e4944335c327"},
        source: "source/marketplace-api",
        resourceId: UUID {uuid: "174f00f5-dc7c-4078-8937-26de60ff5418"},
        resourceType: "availabilityException",
        resource: null,
        previousValues: {
          attributes: {
            seats: 0,
            start: new Date("2020-12-03T00:00:00.000Z"),
            end: new Date("2020-12-04T00:00:00.000Z")
          },
          relationships: {
            listing: {data: {id: UUID {uuid: "6b19f8a8-d87a-47ae-9f59-658befb07613"}, type: "listing"}}
          }
        },
        auditData: {
          userId: UUID {uuid: "5cf4c0eb-513f-419b-a8be-bdb6c14be10a"},
          adminId: null,
          clientId: UUID {uuid: "69ea8198-201c-48c4-a3bb-78b38e4059b0"},
          requestId: UUID {uuid: "636427e1-edde-46f3-a541-928e14279f61"}
        }
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: null,
    totalPages: null,
    page: 1,
    perPage: 100,
    paginationUnsupported: true
  }
}

Query all events. Returns 0 or more events.

By default this query returns events starting from the earliest available one in the marketplace. Optionally, query events starting from given sequence ID or timestamp and/or filter by different criteria.

Events are always returned in ascending order of their sequence ID. This means that the sequence ID of the last received event can be used to query subsequent events using the startAfterSequenceId query parameter.

Note that there can be delay between an action taking place on the marketplace and the corresponding event becoming available in queries.

This endpoint does not support the page query parameter. Use the startAfterSequenceId using the sequence ID of the last obtained event to query subsequent events.

Query parameters

Parameter	Description
startAfterSequenceId	(integer, optional) Return events with sequence ID strictly larger than the given sequence ID. At most one of `startAfterSequenceId` and `createdAtStart` can be given.
createdAtStart	(timestamp, optional) Return only events with `createdAt` timestamp greater than or equal to the given timestamp (in ISO 8601 format). The timestamp can be at most 90 days in the past (for live marketplaces) or at most 7 days in the past (for dev and test marketplaces). At most one of `startAfterSequenceId` and `createdAtStart` can be given.
resourceId	(UUID, optional) Return only events for resource with the given ID. At most one of `resourceId` and `relatedResourceId` can be given.
relatedResourceId	(UUID, optional) Return only events for resources that are related to the resource with the given ID. At most one of `resourceId` and `relatedResourceId` can be given. See Querying events for related resources for details.
eventTypes	(comma separated list of strings, optional) List of event types to filter the results by. Only events with one of the given event types are returned. In addition to the individual event types, it is possible to give the corresponding resource type name, which has the effect of matching all events for that resource type (e.g. `listing` matches any of `listing/created`, `listing/updated` or `listing/deleted`, etc).

The relatedResourceId query parameter allows filtering events that are about a resource that is related to a given resource. For this query, an event is considered to be about a related resource if any of these is true:

the event is about the given resource itself
the event is about a resource that has any cardinality-one relationship to the given resource.

See the documentation of each Integration API resource type for a list of the supported relationships.

For example, if relatedResourceId is set to some listing ID, the returned events may include, among others, events for transactions for that listing, because of the listing relationship of transaction resources. Likewise, if relatedResourceId is set to some user ID, the returned events may include events for transactions where the given user is either provider or a customer, because of the provider and customer relationships of transaction resources.

Note that the marketplace relationship that some resources have is ignored when querying with relatedResourceId.

Integration API reference

Authentication

Sharetribe Integration SDK

Revoking the refresh token

Rate limits

Marketplace

marketplace resource format

Show marketplace

Users

user resource format

user identity provider

user states

user permissionSet

user relationships

Show user

Query parameters

Query users

Query parameters

Extended data filtering

Controlling sorting of users

Pagination limits

Update user profile

Body parameters

Common errors

Approve user

Body parameters

Update permissions

Body parameters

Stripe Account

stripeAccount resource format

Listings

listing resource format

listing states

listing availability plan

listing relationships

Show listing

Query parameters

Query listings

Query parameters

Price filtering

Extended data filtering

Availability filtering

Controlling sorting of listings

Pagination limits

Create listing

Body parameters

Common errors

Update listing

Body parameters

Close listing

Body parameters

Open listing

Body parameters

Approve listing

Body parameters

Availability exceptions

availabilityException resource format

availabilityException relationships

Query availability exceptions

Query parameters

Create availability exceptions

Body parameters

Delete availability exceptions

Body parameters

Images

image resource format

Image variants

Predefined image variants

Custom image variants

Variant fit modes

Upload image

Multipart body parameters

Common errors

Transactions

transaction resource format

transaction relationships

Show transaction

Query parameters

Query transactions

Query parameters

`marketplace` resource format

`user` resource format

`user` identity provider

`user` states

`user` permissionSet

`user` relationships

`stripeAccount` resource format

`listing` resource format

`listing` states

`listing` availability plan

`listing` relationships

`availabilityException` resource format

`availabilityException` relationships

`image` resource format

`transaction` resource format

`transaction` relationships

`booking` resource format

`booking` states

`booking` relationships

`stock` resource format

`stockAdjustment` resource format

`stockAdjustment` relationships

`stockReservation` resource format

`stockReservation` relationships

`review` resource format

`review` relationships

`message` resource format

`message` relationships

`event` resource format

`event` relationships