NAV Navbar
JavaScript curl
  • Integration API
  • Authentication
  • Marketplace
  • Users
  • Stripe Account
  • Listings
  • Availability exceptions
  • Images
  • Transactions
  • Bookings
  • Reviews
  • Messages
  • Integration API

    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-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 Flex Integration SDK, which provides convenience methods of handling authentication and tokens. Using the SDK is recommended over direct API access.

    Sharetribe Flex Integration SDK

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

    Sharetribe Flex 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.

    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) The marketplace description.

    Show marketplace

    HTTP request

    GET /v1/integration_api/marketplace/show

    Example request

    $ curl 'https://flex-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,
          "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
            }
          }
        }
      }
    }
    
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "user",
        attributes: {
          banned: false,
          deleted: false,
          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
            }
          }
        }
      }
    }
    

    The user API resource represents public data about marketplace users.

    user resource format

    Attribute Description
    banned (boolean) Flag indicating whether the user is banned. Banned users have all other attributes set to null or false.
    deleted (boolean) Flag indicating whether the user is deleted. Deleted users have all other attributes set to null or false.
    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.
    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.

    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.

    Show user

    HTTP request

    GET /v1/integration_api/users/show

    Example request

    $ curl 'https://flex-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,
          "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
            }
          }
        }
      }
    }
    
    // res.data
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "user",
        attributes: {
          banned: false,
          deleted: false,
          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
            }
          }
        }
      }
    }
    

    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 (optiona, string) The email address of the user.

    Query users

    HTTP request

    GET /v1/integration_api/users/query

    Example request

    $ curl 'https://flex-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,
            "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,
            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.

    Update user profile

    HTTP request

    POST /v1/integration_api/users/update_profile

    Example request

    $ curl -X POST 'https://flex-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 '{
      "firstName": "Alex",
      "profileImageId": "c5b75c21-5b30-40bf-a114-4688c07128ef",
      "protectedData": {
        "phoneNumber": "+1-202-555-4444"
      },
      "privateData": {
        "discoveredServiceVia": "Twitter"
      },
      "metadata": {
        "identityVerified": true
      }
    }'
    
    integrationSdk.users.updateProfile({
      firstName: "Alex",
      profileImageId: UUID {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,
          "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,
          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. Defaults to first name plus initial of last name.
    bio (string, optional) User's 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.

    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.

    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.

    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.

    Show listing

    HTTP request

    GET /v1/integration_api/listings/show

    Example request

    $ curl 'https://flex-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-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.
    states (comma separated list of strings, optional) List of 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.
    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 keywords or origin query parameters. Default is createdAt See Sorting 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:

    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 toVALUE.
    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:

    Pagination is not supported in the following cases:

    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.

    Sorting

    The query results are ordered subject to the following rules:

    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 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.
    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.

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

    Examples:

    Update listing

    HTTP request

    POST /v1/integration_api/listings/update

    Example request

    $ curl -X POST 'https://flex-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 1000 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. Pass null to remove the availability plan from the listing.
    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 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 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.

    Close listing

    HTTP request

    POST /v1/integration_api/listings/close

    Example request

    $ curl -X POST 'https://flex-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.

    Open listing

    HTTP request

    POST /v1/integration_api/listings/open

    Example request

    $ curl -X POST 'https://flex-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.

    Approve listing

    HTTP request

    POST /v1/integration_api/listings/approve

    Example request

    $ curl -X POST 'https://flex-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.

    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.

    Query availability exceptions

    HTTP request

    GET /v1/integration_api/availability_exceptions/query

    Example request

    $ curl 'https://flex-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 one day in the past and 365 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 365 days in the future.

    Create availability exceptions

    HTTP request

    POST /v1/integration_api/availability_exceptions/create

    Example request

    $ curl -X POST 'https://flex-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.

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

    Delete availability exceptions

    HTTP request

    POST /v1/integration_api/availability_exceptions/delete

    Example request

    $ curl -X POST 'https://flex-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.

    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.

    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.

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

    Variant Transformation Width Height
    default fit, clip 750px 750px
    landscape-crop fit, crop 400px 267px
    landscape-crop2x fit, crop 800px 533px
    landscape-crop4x fit, crop 1600px 1066px
    landscape-crop6x fit, crop 2400px 1602px
    scaled-small fit, clip 320px 320px
    scaled-medium fit, clip 750px 750px
    scaled-large fit, clip 1024px 1024px
    scaled-xlarge fit, clip 2400px 2400px
    square-small fit, crop 240px 240px
    square-small2x fit, crop 480px 480px
    facebook fit, crop 1200px 630px
    twitter fit, crop 600px 314px
    Transformation Description
    fit, clip 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.
    fit, 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-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

    Parameter Description
    image The image content.

    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"
          },
          "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"
          },
          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.
    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.
    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.
    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. Alternatively, use /messages/query API endpoint. Supported nested relationships: messages.sender, messages.sender.profileImage.

    Show transaction

    HTTP request

    GET /v1/integration_api/transactions/show

    Example request

    $ curl 'https://flex-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-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.

    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 Description
    pending A new booking that has been requested by a customer.
    accepted A booking that has been accepted by the provider.
    declined A booking that has been declined by the provider or customer before it was accepted.
    cancelled A booking that has been cancelled.

    booking relationships

    Relationship Resource type Cardinality Description
    transaction transaction one The transaction corresponding to a given booking. Supported nested relationships: transaction.customer and transaction.customer.profileImage.

    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"
        }
      }
    }
    
    {
      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")
        }
      }
    }
    

    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.

    review relationships

    Relationship Resource type Cardinality Description
    author user one The user that wrote the review. Supported nested relationships: author.profileImage.
    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. Supported nested relationships: subject.profileImage.

    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.