---
title: Upload Image
framework: retentionmessaging
role: symbol
role_heading: Web Service Endpoint
path: retentionmessaging/upload-image
---

# Upload Image

Uploads an image to use for retention messaging.

## URL

PUT https://api.storekit.apple.com/inApps/v1/messaging/image/{imageIdentifier}

## Sandbox URL

PUT https://api.storekit-sandbox.apple.com/inApps/v1/messaging/image/{imageIdentifier}

## Path Parameters

imageIdentifier: A UUID you provide to uniquely identify the image you upload.

## Query Parameters

imageSize: The size of the image you upload.

## Response Codes

200 OK: Request succeeded. 400 Bad Request: The request is invalid and unacceptable. 401 Unauthorized: The JSON Web Token (JWT) in the authorization header is invalid. For more information, see Generating JSON Web Tokens for API requests. 403 Forbidden: The request is forbidden because the system reached the maximum number of uploaded images. 409 Conflict: The image identifier already exists. 429 : The request exceeded the rate limit. For more information, see Identifying rate limits. 500 Internal Server Error: Server error. Try again later.

## Mentioned in

Identifying rate limits Retention Messaging API changelog Setting up retention messages

## Discussion

Discussion Call this endpoint to upload an image that you can associate with a message or a bullet point within the message. You provide a unique imageIdentifier to identify each image you upload. You can upload image files that meet the following requirements: Format: PNG Doesn’t have transparency note: Ensure the images you upload work equally well with both light and dark modes. The maximum number of images you can configure for each app is 2000. The endpoint returns a MaximumNumberOfImagesReachedError response if an attempt to upload an image exceeds this limit. Call Delete Image to delete images. Use full-size images for a message, or the smaller bullet point-size images to use as bullet points. Upload full-size images A full-size image is up to 3840 × 2160 pixels, where the width must be 3840 pixels, and the height can be between 160 to 2160 pixels. You can add alternative text for images when you call Upload Message and associate an image with a message using UploadMessageImage. Upload images for bullet points Images you use for bullet points are 1024 x 1024 pixels. You can add alternative text for the bullet point images when you supply bulletPoints in the UploadMessageRequestBody. note: This endpoint isn’t idempotent. If you attempt to upload an image and reuse a previously configured imageIdentifier, the endpoint returns the ImageAlreadyExistsError response. Determine whether an image is ready to display Immediately after you upload an image, its imageState is PENDING. Apple checks the images, and sets the image state to APPROVED to indicate the system can display them in retention messaging. Call the Get Image List endpoint to check the current state of images you upload. In the sandbox testing environment, the system automatically sets the message and image states to APPROVED.

## HTTP Body

The image file to upload.

## See Also

### Image configuration

- [Delete Image](retentionmessaging/delete-image.md)
- [Get Image List](retentionmessaging/get-image-list.md)
- [GetImageListResponse](retentionmessaging/getimagelistresponse.md)
- [GetImageListResponseItem](retentionmessaging/getimagelistresponseitem.md)